plan_my_stuff 0.3.0 → 0.5.0

data/lib/plan_my_stuff/project.rb

@@ -1,51 +1,19 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  # Wraps a GitHub Projects V2 project with its statuses, items, and fields.
-  # Class methods provide the public API for CRUD and query operations.
+  # Wraps a regular (non-testing) GitHub Projects V2 project.
+  # Inherits all shared find/list/update/hydrate behavior from BaseProject.
+  # Adds +create!+ for regular project creation, and overrides +find+/+list+
+  # to exclude testing projects. For testing projects use +TestingProject+;
+  # for either type use +BaseProject.find+/+list+.
   #
   # Follows an ActiveRecord-style pattern:
   # - `Project.find` / `Project.list` return persisted instances
   # - `ProjectItem.add_item` / `ProjectItem.add_draft_item` for adding items
   # - `ProjectItem.move_item` / `ProjectItem.assign` for item mutations
-  class Project < PlanMyStuff::ApplicationRecord
-    MAX_AUTO_PAGINATE_ITEMS = 500
-    ITEMS_PER_PAGE = 100
-
-    # @return [String] GitHub node ID
-    attr_reader :id
-    # @return [Integer] project number
-    attr_reader :number
-    # @return [Boolean] whether the project is closed
-    attr_reader :closed
-    # @return [PlanMyStuff::ProjectMetadata] parsed metadata (empty when no PMS metadata present)
-    attr_reader :metadata
-    # @return [String] full readme as stored on GitHub
-    attr_reader :raw_readme
-    # @return [String, nil] project short description (from shortDescription)
-    attr_reader :description
-    # @return [Time, nil] GitHub's updatedAt timestamp
-    attr_reader :updated_at
-
-    # @return [String] project title
-    attr_accessor :title
-    # @return [String] project URL
-    attr_accessor :url
-    # @return [String, nil] user-visible readme content (without metadata comment)
-    attr_accessor :readme
-    # @return [Array<Hash>] status options ({id:, name:})
-    attr_accessor :statuses
-    # @return [Array<Hash>] all field definitions
-    attr_accessor :fields
-    # @return [Array<PlanMyStuff::ProjectItem>] project items
-    attr_accessor :items
-    # @return [String, nil] cursor for next page (only in cursor mode)
-    attr_accessor :next_cursor
-    # @return [Boolean, nil] whether more pages exist (only in cursor mode)
-    attr_accessor :has_next_page
-
+  class Project < PlanMyStuff::BaseProject
     class << self
-      # Creates a new project in the configured organization with PMS metadata.
+      # Creates a new regular project in the configured organization with PMS metadata.
       #
       # @param title [String]
       # @param user [Object, Integer, nil] user object or user_id
@@ -68,7 +36,7 @@ module PlanMyStuff
 
         org_id = resolve_org_id(org)
         data = PlanMyStuff.client.graphql(
-          create_mutation,
+          PlanMyStuff::GraphQL::Queries::CREATE_PROJECT,
           variables: { input: { ownerId: org_id, title: title } },
         )
 
@@ -81,685 +49,54 @@ module PlanMyStuff
         update_input[:shortDescription] = description if description.present?
 
         PlanMyStuff.client.graphql(
-          update_mutation,
+          PlanMyStuff::GraphQL::Queries::UPDATE_PROJECT,
           variables: { input: update_input },
         )
 
         find(project_number)
       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::Project]
-      #
-      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(
-          update_mutation,
-          variables: { input: update_input },
-        )
-
-        find(project_number)
-      end
-
-      # Lists all projects in the configured organization.
-      #
-      # @return [Array<PlanMyStuff::Project>]
-      #
-      def list
-        org = PlanMyStuff.configuration.organization
-        data = PlanMyStuff.client.graphql(list_query, variables: { org: org })
-
-        nodes = data.dig(:organization, :projectsV2, :nodes) || []
-
-        nodes.map { |node| build_summary(node) }
-      end
-
-      # Finds a project by number with its statuses, items, and fields.
+      # Finds a regular project by number. Raises if the project is a testing
+      # project - call +TestingProject.find+ for those, or +BaseProject.find+
+      # if you want either type.
       #
       # @param number [Integer]
       # @param paginate [Symbol] :auto (default) or :cursor
-      # @param cursor [String, nil] pagination cursor for :cursor mode (from a previous call's next_cursor)
+      # @param cursor [String, nil] pagination cursor for :cursor mode
+      #
+      # @raise [ArgumentError] if the project is a testing project
       #
       # @return [PlanMyStuff::Project]
       #
       def find(number, paginate: :auto, cursor: nil)
-        org = PlanMyStuff.configuration.organization
+        project = super
 
-        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")
+        unless project.is_a?(self)
+          raise(ArgumentError, "Project ##{number} is a testing project; use PlanMyStuff::TestingProject.find")
         end
+
+        project
       end
 
-      # Resolves a project number, falling back to config.default_project_number.
+      # Lists all regular projects in the configured organization.
+      # Testing projects are excluded; use +TestingProject.list+ or
+      # +BaseProject.list+ to reach them.
       #
-      # @param project_number [Integer, nil]
-      #
-      # @return [Integer]
+      # @return [Array<PlanMyStuff::Project>]
       #
-      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
-
-        # @return [String]
-        def list_query
-          <<~GRAPHQL
-            query($org: String!) {
-              organization(login: $org) {
-                projectsV2(first: 100) {
-                  nodes {
-                    id
-                    number
-                    title
-                    shortDescription
-                    url
-                    closed
-                    updatedAt
-                  }
-                }
-              }
-            }
-          GRAPHQL
-        end
-
-        # @return [String]
-        def find_query
-          <<~GRAPHQL
-            query($org: String!, $number: Int!, $cursor: String) {
-              organization(login: $org) {
-                projectV2(number: $number) {
-                  id
-                  number
-                  title
-                  shortDescription
-                  readme
-                  url
-                  closed
-                  updatedAt
-                  fields(first: 50) {
-                    nodes {
-                      ... on ProjectV2SingleSelectField {
-                        id
-                        name
-                        options {
-                          id
-                          name
-                        }
-                      }
-                      ... on ProjectV2Field {
-                        id
-                        name
-                      }
-                      ... on ProjectV2IterationField {
-                        id
-                        name
-                      }
-                    }
-                  }
-                  items(first: #{ITEMS_PER_PAGE}, after: $cursor) {
-                    pageInfo {
-                      hasNextPage
-                      endCursor
-                    }
-                    nodes {
-                      id
-                      type
-                      content {
-                        ... on Issue {
-                          id
-                          title
-                          number
-                          url
-                          state
-                          repository { nameWithOwner }
-                        }
-                        ... on PullRequest {
-                          id
-                          title
-                          number
-                          url
-                          state
-                          repository { nameWithOwner }
-                        }
-                        ... on DraftIssue {
-                          id
-                          title
-                        }
-                      }
-                      fieldValues(first: 20) {
-                        nodes {
-                          ... on ProjectV2ItemFieldSingleSelectValue {
-                            name
-                            field {
-                              ... on ProjectV2SingleSelectField {
-                                name
-                              }
-                            }
-                          }
-                          ... on ProjectV2ItemFieldTextValue {
-                            text
-                            field {
-                              ... on ProjectV2Field {
-                                name
-                              }
-                            }
-                          }
-                          ... on ProjectV2ItemFieldUserValue {
-                            users(first: 10) {
-                              nodes {
-                                login
-                              }
-                            }
-                            field {
-                              ... on ProjectV2Field {
-                                name
-                              }
-                            }
-                          }
-                        }
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          GRAPHQL
-        end
-
-        # @return [String]
-        def project_id_query
-          <<~GRAPHQL
-            query($org: String!, $number: Int!) {
-              organization(login: $org) {
-                projectV2(number: $number) {
-                  id
-                }
-              }
-            }
-          GRAPHQL
-        end
-
-        # Builds a summary Project from a list query node.
-        #
-        # @param node [Hash]
-        #
-        # @return [PlanMyStuff::Project]
-        #
-        def build_summary(node)
-          project = new
-          project.__send__(:hydrate_summary, node)
-          project
-        end
-
-        # Builds a detailed Project from a find query response.
-        #
-        # @param graphql_project [Hash]
-        # @param items [Array<Hash>]
-        # @param next_cursor [String, nil]
-        # @param has_next_page [Boolean, nil]
-        #
-        # @return [PlanMyStuff::Project]
-        #
-        def build_detail(graphql_project, items:, next_cursor: nil, has_next_page: nil)
-          project = new
-          project.__send__(
-            :hydrate_detail,
-            graphql_project,
-            items: items,
-            next_cursor: next_cursor,
-            has_next_page: has_next_page,
-          )
-          project
-        end
-
-        # @param org [String]
-        # @param number [Integer]
-        #
-        # @return [PlanMyStuff::Project]
-        #
-        def find_auto_paginated(org, number)
-          all_items = []
-          cursor = nil
-          raw_project = 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)
-        end
-
-        # @param org [String]
-        # @param number [Integer]
-        # @param cursor [String, nil]
-        #
-        # @return [PlanMyStuff::Project]
-        #
-        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(find_query, 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],
-            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),
-          }
-        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(
-            project_id_query,
-            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(
-            org_id_query,
-            variables: { org: org },
-          )
-
-          data.dig(:organization, :id)
-        end
-
-        # @return [String]
-        def org_id_query
-          <<~GRAPHQL
-            query($org: String!) {
-              organization(login: $org) {
-                id
-              }
-            }
-          GRAPHQL
-        end
-
-        # @return [String]
-        def create_mutation
-          <<~GRAPHQL
-            mutation($input: CreateProjectV2Input!) {
-              createProjectV2(input: $input) {
-                projectV2 {
-                  id
-                  number
-                }
-              }
-            }
-          GRAPHQL
-        end
-
-        # @return [String]
-        def update_mutation
-          <<~GRAPHQL
-            mutation($input: UpdateProjectV2Input!) {
-              updateProjectV2(input: $input) {
-                projectV2 {
-                  id
-                  number
-                }
-              }
-            }
-          GRAPHQL
-        end
-    end
-
-    # @see super
-    def initialize(**attrs)
-      @id = attrs.delete(:id)
-      @number = attrs.delete(:number)
-      @closed = attrs.delete(:closed)
-      @metadata = PlanMyStuff::ProjectMetadata.new
-      @raw_readme = nil
-      @readme = nil
-      @description = nil
-      @updated_at = nil
-      super
-      @statuses ||= []
-      @fields ||= []
-      @items ||= []
-    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 || '')
-        hydrate_from_project(created)
-      else
-        update!(title: title, readme: readme)
+      def list
+        super.select { |p| p.is_a?(self) }
       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
 
-      # Populates this instance from a list query node (summary only).
+      # Returns the item class used to build items for testing projects.
       #
-      # @param node [Hash]
+      # @return [Class]
       #
-      # @return [void]
-      #
-      def hydrate_summary(node)
-        @id = node[:id]
-        @number = node[:number]
-        @title = node[:title]
-        @description = node[:shortDescription]
-        @url = node[:url]
-        @closed = node[:closed]
-        @updated_at = parse_github_time(node[:updatedAt])
-        @persisted = true
-      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)
-        @id = graphql_project[:id]
-        @number = graphql_project[:number]
-        @title = graphql_project[:title]
-        @description = graphql_project[:shortDescription]
-        @url = graphql_project[:url]
-        @closed = graphql_project[:closed]
-        @updated_at = parse_github_time(graphql_project[:updatedAt])
-
-        @raw_readme = graphql_project[:readme] || ''
-        parsed = PlanMyStuff::MetadataParser.parse(@raw_readme)
-        @metadata = PlanMyStuff::ProjectMetadata.from_hash(parsed[:metadata])
-        @readme = parsed[:body]
-
-        fields_nodes = graphql_project.dig(:fields, :nodes) || []
-        @statuses = extract_statuses(fields_nodes)
-        @fields = extract_fields(fields_nodes)
-        @items = items.map { |item_hash| ProjectItem.build(item_hash, project: self) }
-        @next_cursor = next_cursor
-        @has_next_page = has_next_page
-        @persisted = true
-      end
-
-      # Copies attributes from another Project instance into self.
-      #
-      # @param other [PlanMyStuff::Project]
-      #
-      # @return [void]
-      #
-      def hydrate_from_project(other)
-        @id = other.id
-        @number = other.number
-        @title = other.title
-        @description = other.description
-        @url = other.url
-        @closed = other.closed
-        @updated_at = other.updated_at
-        @raw_readme = other.raw_readme
-        @readme = other.readme
-        @metadata = other.metadata
-        @statuses = other.statuses
-        @fields = other.fields
-        @items = other.items
-        @next_cursor = other.next_cursor
-        @has_next_page = other.has_next_page
-        @persisted = true
-      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
-
-      # 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
+      def item_class
+        PlanMyStuff::ProjectItem
       end
   end
 end