plan_my_stuff 0.1.0

data/lib/plan_my_stuff/markdown.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+
+module PlanMyStuff
+  module Markdown
+    class << self
+      # Renders markdown text to HTML using the configured renderer.
+      # Per-call options are deep-merged on top of config.markdown_options.
+      #
+      # @param text [String] raw markdown text
+      # @param options [Hash] renderer-specific options (merged over config defaults)
+      #   For :commonmarker - passed as `options:` to `Commonmarker.to_html`
+      #   For :redcarpet - :render_options and :renderer are extracted for the HTML renderer;
+      #     remaining keys are passed as extensions to `Redcarpet::Markdown.new`
+      #
+      # @return [String] rendered HTML
+      #
+      def render(text, options = {})
+        config = PlanMyStuff.configuration
+        merged = config.markdown_options.deep_merge(options)
+
+        case config.markdown_renderer
+        when :commonmarker
+          render_commonmarker(text, merged)
+        when :redcarpet
+          render_redcarpet(text, merged)
+        when nil
+          "<code>#{text}</code>"
+        else
+          raise(
+            ArgumentError,
+            "Unknown markdown_renderer: #{config.markdown_renderer.inspect}. Use :commonmarker, :redcarpet, or nil.",
+          )
+        end
+      end
+
+      private
+
+        # @param text [String]
+        # @param options [Hash]
+        #
+        # @return [String]
+        #
+        def render_commonmarker(text, options)
+          require('commonmarker') unless defined?(Commonmarker)
+
+          if options.empty?
+            Commonmarker.to_html(text)
+          else
+            Commonmarker.to_html(text, options: options)
+          end
+        rescue LoadError
+          raise(
+            PlanMyStuff::Error,
+            'commonmarker gem is required when markdown_renderer is :commonmarker. ' \
+              "Add gem 'commonmarker' to your Gemfile.",
+          )
+        end
+
+        # @param text [String]
+        # @param options [Hash]
+        #
+        # @return [String]
+        #
+        def render_redcarpet(text, options)
+          require('redcarpet') unless defined?(Redcarpet)
+
+          options = options.dup
+          render_options = options.delete(:render_options) || {}
+          renderer_class = options.delete(:renderer) || Redcarpet::Render::HTML
+
+          Redcarpet::Markdown.new(renderer_class.new(render_options), options).render(text)
+        rescue LoadError
+          raise(
+            PlanMyStuff::Error,
+            'redcarpet gem is required when markdown_renderer is :redcarpet. ' \
+              "Add gem 'redcarpet' to your Gemfile.",
+          )
+        end
+    end
+  end
+end

data/lib/plan_my_stuff/metadata_parser.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PlanMyStuff
+  module MetadataParser
+    METADATA_PATTERN = /\A<!-- pms-metadata:(.*?) -->\n*/m
+
+    module_function
+
+    # Extracts metadata JSON from the raw body
+    #
+    # @param raw_body [String, nil]
+    #
+    # @return [Hash{Symbol => Hash, String}] :metadata (Hash, empty when absent) and :body (String)
+    #
+    def parse(raw_body)
+      return { metadata: {}, body: '' } if raw_body.blank?
+
+      match = raw_body.match(METADATA_PATTERN)
+      return { metadata: {}, body: raw_body } if match.nil?
+
+      metadata = JSON.parse(match[1], symbolize_names: true)
+      body = raw_body.sub(METADATA_PATTERN, '')
+
+      { metadata: metadata, body: body }
+    rescue JSON::ParserError
+      { metadata: {}, body: raw_body }
+    end
+
+    # Serializes a metadata hash and body into the stored format
+    #
+    # @param metadata [Hash, PlanMyStuff::CustomFields]
+    # @param body [String]
+    #
+    # @return [String]
+    #
+    def serialize(metadata, body)
+      if !metadata.is_a?(Hash) && !metadata.is_a?(PlanMyStuff::CustomFields)
+        raise(ArgumentError, "metadata must be a Hash or PlanMyStuff::CustomFields, got #{metadata.class}")
+      end
+
+      json =
+        if metadata.is_a?(PlanMyStuff::CustomFields)
+          metadata.to_json
+        else
+          JSON.pretty_generate(metadata)
+        end
+
+      "<!-- pms-metadata:#{json} -->\n\n#{body}"
+    end
+  end
+end

data/lib/plan_my_stuff/project.rb

@@ -0,0 +1,504 @@
+# 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.
+  #
+  # 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 << self
+      # Creates a new project in the configured organization.
+      #
+      # @param title [String]
+      #
+      # @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>]
+      #
+      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.
+      #
+      # @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)
+      #
+      # @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
+
+        # 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
+        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
+      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]
+        @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
+      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
+  end
+end