plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/project.rb

@@ -1,504 +1,102 @@
 # 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 [String] project title
-    attr_accessor :title
-    # @return [String] project URL
-    attr_accessor :url
-    # @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.
+      # 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
+      # @param visibility [String] "public" or "internal"
+      # @param custom_fields [Hash] app-defined field values
+      # @param readme [String] user-visible readme content
+      # @param description [String, nil] project short description
       #
-      # @return [Object]
-      #
-      def create(title:)
-        raise(NotImplementedError, "#{name}.create is not yet implemented")
-      end
-
-      # Updates an existing project.
-      #
-      # @param project_number [Integer]
-      # @param title [String, nil]
-      #
-      # @return [Object]
-      #
-      def update(project_number:, title: nil)
-        raise(NotImplementedError, "#{name}.update is not yet implemented")
-      end
-
-      # Lists all projects in the configured organization.
-      #
-      # @return [Array<PlanMyStuff::Project>]
+      # @return [PlanMyStuff::Project]
       #
-      def list
+      def create!(title:, user: nil, visibility: 'internal', custom_fields: {}, readme: '', description: nil)
         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) }
+        project_metadata = PlanMyStuff::ProjectMetadata.build(
+          user: user,
+          visibility: visibility,
+          custom_fields: custom_fields,
+        )
+        project_metadata.validate_custom_fields!
+
+        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 },
+        )
+
+        find(project_number)
       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.
+      #
+      # @raise [ArgumentError] if the project is a testing project
       #
       # @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
       #
       # @return [PlanMyStuff::Project]
       #
       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
-
-      private
+        project = super
 
-        # 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
-
-        # @return [String]
-        def list_query
-          <<~GRAPHQL
-            query($org: String!) {
-              organization(login: $org) {
-                projectsV2(first: 100) {
-                  nodes {
-                    id
-                    number
-                    title
-                    url
-                    closed
-                  }
-                }
-              }
-            }
-          GRAPHQL
-        end
-
-        # @return [String]
-        def find_query
-          <<~GRAPHQL
-            query($org: String!, $number: Int!, $cursor: String) {
-              organization(login: $org) {
-                projectV2(number: $number) {
-                  id
-                  number
-                  title
-                  url
-                  closed
-                  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
-                        }
-                        ... on PullRequest {
-                          id
-                          title
-                          number
-                          url
-                          state
-                        }
-                        ... 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
+        unless project.is_a?(self)
+          raise(ArgumentError, "Project ##{number} is a testing project; use PlanMyStuff::TestingProject.find")
         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) || []
-
-          {
-            id: item[:id],
-            type: item[:type],
-            content_node_id: content[:id],
-            title: content[:title],
-            number: content[:number],
-            url: content[:url],
-            state: content[:state],
-            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
-    end
-
-    # @see super
-    def initialize(**attrs)
-      @id = attrs.delete(:id)
-      @number = attrs.delete(:number)
-      @closed = attrs.delete(:closed)
-      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
-
-    private
-
-      # Populates this instance from a list query node (summary only).
-      #
-      # @param node [Hash]
-      #
-      # @return [void]
-      #
-      def hydrate_summary(node)
-        @id = node[:id]
-        @number = node[:number]
-        @title = node[:title]
-        @url = node[:url]
-        @closed = node[:closed]
-        @persisted = true
+        project
       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]
+      # Lists all regular projects in the configured organization.
+      # Testing projects are excluded; use +TestingProject.list+ or
+      # +BaseProject.list+ to reach them.
       #
-      # @return [void]
+      # @return [Array<PlanMyStuff::Project>]
       #
-      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]
-        @url = graphql_project[:url]
-        @closed = graphql_project[:closed]
-
-        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
+      def list
+        super.select { |p| p.is_a?(self) }
       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
+    private
 
-      # @param fields_nodes [Array<Hash>]
+      # Returns the item class used to build items for regular projects.
       #
-      # @return [Array<Hash>]
+      # @return [Class]
       #
-      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