plan_my_stuff 0.1.0

data/lib/plan_my_stuff/issue.rb

@@ -0,0 +1,486 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Wraps a GitHub issue with parsed PMS metadata and comments.
+  # Class methods provide the public API for CRUD operations.
+  #
+  # Follows an ActiveRecord-style pattern:
+  # - `Issue.new(**attrs)` creates an unpersisted instance
+  # - `Issue.create!` / `Issue.find` / `Issue.list` return persisted instances
+  # - `issue.save!` / `issue.update!` / `issue.reload` for persistence
+  class Issue < PlanMyStuff::ApplicationRecord
+    # @return [Integer] GitHub issue number
+    attr_reader :number
+    # @return [String] full body as stored on GitHub
+    attr_reader :raw_body
+    # @return [PlanMyStuff::IssueMetadata] parsed metadata (empty when no PMS metadata present)
+    attr_reader :metadata
+
+    # @return [String] issue title
+    attr_accessor :title
+    # @return [String] issue body without the metadata HTML comment
+    attr_writer :body
+    # @return [String] issue state ("open" or "closed")
+    attr_accessor :state
+    # @return [Array<String>] label names
+    attr_accessor :labels
+    # @return [String] resolved repo path (e.g. "Org/Repo")
+    attr_accessor :repo
+
+    class << self
+      # Creates a GitHub issue with PMS metadata embedded in the body.
+      #
+      # @param title [String]
+      # @param body [String]
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param labels [Array<String>]
+      # @param user [Object, Integer] user object or user_id
+      # @param metadata [Hash] custom fields hash
+      # @param add_to_project [Boolean, Integer, nil]
+      # @param visibility_allowlist [Array<Integer>] user IDs for internal comment access
+      #
+      # @return [PlanMyStuff::Issue]
+      #
+      def create!(
+        title:,
+        body:,
+        repo: nil,
+        labels: [],
+        user: nil,
+        metadata: {},
+        add_to_project: nil,
+        visibility_allowlist: []
+      )
+        raise(ValidationError.new('body must be present', field: :body, expected_type: :string)) if body.blank?
+
+        client = PlanMyStuff.client
+        resolved_repo = client.resolve_repo(repo)
+
+        issue_metadata = IssueMetadata.build(
+          user: user,
+          custom_fields: metadata,
+        )
+        issue_metadata.visibility_allowlist = Array.wrap(visibility_allowlist)
+
+        serialized_body = MetadataParser.serialize(issue_metadata.to_h, '')
+
+        options = {}
+        options[:labels] = labels if labels.any?
+
+        result = client.rest(:create_issue, resolved_repo, title, serialized_body, **options)
+
+        issue = build(result, repo: resolved_repo)
+
+        if add_to_project.present?
+          project_number = resolve_project_number(add_to_project)
+          ProjectItem.create!(issue, project_number: project_number)
+        end
+
+        Comment.create!(
+          issue: issue,
+          body: body,
+          user: user,
+          visibility: issue_metadata.visibility.to_sym,
+          skip_responded: true,
+          issue_body: true,
+        )
+
+        issue
+      end
+
+      # Updates an existing GitHub issue.
+      #
+      # @param number [Integer]
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param title [String, nil]
+      # @param body [String, nil]
+      # @param metadata [Hash, nil] custom fields to merge into existing metadata
+      # @param labels [Array<String>, nil]
+      # @param state [Symbol, nil] :open or :closed
+      #
+      # @return [Object]
+      #
+      def update!(number:, repo: nil, title: nil, body: nil, metadata: nil, labels: nil, state: nil, assignees: nil)
+        client = PlanMyStuff.client
+        resolved_repo = client.resolve_repo(repo)
+
+        options = {}
+        options[:title] = title unless title.nil?
+        options[:labels] = labels unless labels.nil?
+        options[:state] = state.to_s unless state.nil?
+        options[:assignees] = Array.wrap(assignees) unless assignees.nil?
+
+        if metadata
+          current = client.rest(:issue, resolved_repo, number)
+          current_body = current.respond_to?(:body) ? current.body : current[:body]
+          parsed = MetadataParser.parse(current_body)
+          existing_metadata = parsed[:metadata]
+
+          merged_custom_fields = (existing_metadata[:custom_fields] || {}).merge(metadata[:custom_fields] || {})
+          existing_metadata = existing_metadata.merge(metadata)
+          existing_metadata[:custom_fields] = merged_custom_fields
+
+          existing_metadata[:updated_at] = Time.now.utc.iso8601
+          options[:body] = MetadataParser.serialize(existing_metadata, '')
+        end
+
+        update_body_comment(number, resolved_repo, body) if body
+
+        client.rest(:update_issue, resolved_repo, number, **options) if options.any?
+      end
+
+      # Finds a single GitHub issue by number and parses its PMS metadata.
+      #
+      # @param number [Integer]
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      #
+      # @return [PlanMyStuff::Issue]
+      #
+      def find(number, repo: nil)
+        client = PlanMyStuff.client
+        resolved_repo = client.resolve_repo(repo)
+
+        github_issue = client.rest(:issue, resolved_repo, number)
+
+        if github_issue.respond_to?(:pull_request) && github_issue.pull_request
+          raise(Octokit::NotFound, { method: 'GET', url: "repos/#{resolved_repo}/issues/#{number}" })
+        end
+
+        build(github_issue, repo: resolved_repo)
+      end
+
+      # Lists GitHub issues with optional filters and pagination.
+      #
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param state [Symbol] :open, :closed, or :all
+      # @param labels [Array<String>]
+      # @param page [Integer]
+      # @param per_page [Integer]
+      #
+      # @return [Array<PlanMyStuff::Issue>]
+      #
+      def list(repo: nil, state: :open, labels: [], page: 1, per_page: 25)
+        client = PlanMyStuff.client
+        resolved_repo = client.resolve_repo(repo)
+
+        options = { state: state.to_s, page: page, per_page: per_page }
+        options[:labels] = labels.join(',') if labels.any?
+
+        github_issues = client.rest(:list_issues, resolved_repo, **options)
+        github_issues.filter_map do |gi|
+          next if gi.respond_to?(:pull_request) && gi.pull_request
+
+          build(gi, repo: resolved_repo)
+        end
+      end
+
+      # Adds user IDs to the visibility allowlist of an issue's metadata.
+      #
+      # @param number [Integer]
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param user_ids [Array<Integer>]
+      #
+      # @return [Object] Octokit response
+      #
+      def add_viewers(number:, user_ids:, repo: nil)
+        modify_allowlist(number: number, repo: repo) do |allowlist|
+          allowlist | Array.wrap(user_ids)
+        end
+      end
+
+      # Removes user IDs from the visibility allowlist of an issue's metadata.
+      #
+      # @param number [Integer]
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param user_ids [Array<Integer>]
+      #
+      # @return [Object] Octokit response
+      #
+      def remove_viewers(number:, user_ids:, repo: nil)
+        modify_allowlist(number: number, repo: repo) do |allowlist|
+          allowlist - Array.wrap(user_ids)
+        end
+      end
+
+      private
+
+        # Hydrates an Issue from a GitHub API response.
+        #
+        # @param github_issue [Object] Octokit issue response
+        # @param repo [String] resolved repo path
+        #
+        # @return [PlanMyStuff::Issue]
+        #
+        def build(github_issue, repo:)
+          issue = new
+          issue.__send__(:hydrate_from_github, github_issue, repo: repo)
+          issue
+        end
+
+        # @return [Integer]
+        def resolve_project_number(add_to_project)
+          return add_to_project unless add_to_project == true
+
+          PlanMyStuff.configuration.default_project_number ||
+            raise(ArgumentError, 'add_to_project: true requires config.default_project_number to be set')
+        end
+
+        # Reads an issue's metadata, yields the allowlist for modification,
+        # and PATCHes the issue body with the updated allowlist.
+        #
+        # @param number [Integer]
+        # @param repo [Symbol, String, nil]
+        #
+        # @return [Object] Octokit response
+        #
+        def modify_allowlist(number:, repo:)
+          client = PlanMyStuff.client
+          resolved_repo = client.resolve_repo(repo)
+
+          current = client.rest(:issue, resolved_repo, number)
+          current_body = current.respond_to?(:body) ? current.body : current[:body]
+          parsed = MetadataParser.parse(current_body)
+
+          existing_metadata = parsed[:metadata]
+          allowlist = Array.wrap(existing_metadata[:visibility_allowlist])
+          existing_metadata[:visibility_allowlist] = yield(allowlist)
+          existing_metadata[:updated_at] = Time.now.utc.iso8601
+
+          new_body = MetadataParser.serialize(existing_metadata, parsed[:body])
+          client.rest(:update_issue, resolved_repo, number, body: new_body)
+        end
+
+        # Finds the first PMS comment on an issue and updates its body content,
+        # preserving the comment header and metadata.
+        #
+        # @param number [Integer] issue number
+        # @param resolved_repo [String] resolved repo path
+        # @param new_body [String] new body content
+        #
+        # @return [void]
+        #
+        def update_body_comment(number, resolved_repo, new_body)
+          issue = find(number, repo: resolved_repo)
+          body_comment = issue.body_comment
+          raise(PlanMyStuff::Error, "No body comment found on issue ##{number}") if body_comment.nil?
+
+          header = body_comment.header
+
+          updated_body =
+            if header.present?
+              "#{header}\n\n#{new_body}"
+            else
+              new_body
+            end
+
+          body_comment.update!(body: updated_body)
+        end
+    end
+
+    def initialize(**attrs)
+      @number = attrs.delete(:number)
+      @raw_body = nil
+      @metadata = IssueMetadata.new
+      super
+      @labels ||= []
+    end
+
+    # Persists the issue. 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,
+          body: body,
+          repo: repo,
+          labels: labels || [],
+        )
+        hydrate_from_issue(created)
+      else
+        update!(body: body, state: state, labels: labels)
+      end
+
+      self
+    end
+
+    # Updates this issue on GitHub. Raises StaleObjectError if the remote
+    # has been modified since this instance was loaded.
+    #
+    # @param attrs [Hash] attributes to update (title:, body:, state:, labels:, metadata:)
+    #
+    # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
+    #
+    # @return [self]
+    #
+    def update!(**attrs)
+      raise_if_stale!
+
+      self.class.update!(
+        number: number,
+        repo: repo,
+        **attrs,
+      )
+
+      reload
+    end
+
+    # Re-fetches this issue from GitHub and updates all local attributes.
+    #
+    # @return [self]
+    #
+    def reload
+      fresh = self.class.find(number, repo: repo)
+      hydrate_from_issue(fresh)
+      self
+    end
+
+    # Lazy-loads and memoizes comments from the GitHub API.
+    #
+    # @return [Array<PlanMyStuff::Comment>]
+    #
+    def comments
+      @comments ||= load_comments
+    end
+
+    # @return [Boolean]
+    def pms_issue?
+      metadata.schema_version.present?
+    end
+
+    # @return [Array<PlanMyStuff::Comment>] only comments created via PMS
+    def pms_comments
+      comments.select(&:pms_comment?)
+    end
+
+    # Returns the comment marked as the issue body, if any.
+    #
+    # @return [PlanMyStuff::Comment, nil]
+    #
+    def body_comment
+      pms_comments.find { |c| c.metadata.issue_body? }
+    end
+
+    # Returns the issue body content. For PMS issues, this is the body
+    # from the body comment (stripped of its header). Falls back to the
+    # parsed issue body for non-PMS issues.
+    #
+    # @return [String, nil]
+    #
+    def body
+      return @body if new_record?
+
+      return @body unless pms_issue?
+
+      bc = body_comment
+      return bc.body_without_header if bc.present?
+
+      @body
+    end
+
+    # Delegates visibility check to metadata.
+    # Non-PMS issues are always visible.
+    #
+    # @param user [Object, Integer] user object or user_id
+    #
+    # @return [Boolean]
+    #
+    def visible_to?(user)
+      if pms_issue?
+        metadata.visible_to?(user)
+      else
+        UserResolver.support?(UserResolver.resolve(user))
+      end
+    end
+
+    private
+
+      # Populates this instance from a GitHub API response.
+      #
+      # @param github_issue [Object] Octokit issue response
+      # @param repo [String] resolved repo path
+      #
+      # @return [void]
+      #
+      def hydrate_from_github(github_issue, repo:)
+        @number = read_field(github_issue, :number)
+        @title = read_field(github_issue, :title)
+        @state = read_field(github_issue, :state)
+        @raw_body = read_field(github_issue, :body) || ''
+        @labels = extract_labels(github_issue)
+        @repo = repo
+
+        parsed = MetadataParser.parse(@raw_body)
+        @metadata = IssueMetadata.from_hash(parsed[:metadata])
+        @body = parsed[:body]
+        @persisted = true
+        @comments = nil
+      end
+
+      # Copies attributes from another Issue instance into self.
+      #
+      # @param other [PlanMyStuff::Issue]
+      #
+      # @return [void]
+      #
+      def hydrate_from_issue(other)
+        @number = other.number
+        @title = other.title
+        @state = other.state
+        @body = other.instance_variable_get(:@body)
+        @raw_body = other.raw_body
+        @labels = other.labels
+        @repo = other.repo
+        @metadata = other.metadata
+        @persisted = true
+        @comments = nil
+      end
+
+      # Raises StaleObjectError if the remote issue has been modified
+      # since this instance was loaded.
+      #
+      # @raise [PlanMyStuff::StaleObjectError]
+      #
+      # @return [void]
+      #
+      def raise_if_stale!
+        return if new_record?
+        return if metadata.updated_at.nil?
+
+        remote = self.class.find(number, repo: repo)
+        remote_time = remote.metadata.updated_at
+        local_time = metadata.updated_at
+
+        return if remote_time.nil?
+        return if local_time && remote_time.to_i == local_time.to_i
+
+        raise(StaleObjectError.new(
+          "Issue ##{number} has been modified remotely",
+          local_updated_at: local_time,
+          remote_updated_at: remote_time,
+        ))
+      end
+
+      # @return [Array<String>]
+      def extract_labels(github_issue)
+        raw = read_field(github_issue, :labels) || []
+        raw.map { |label| label_name(label) }
+      end
+
+      # @return [String]
+      def label_name(label)
+        return label.name if label.respond_to?(:name)
+        return label[:name] || label['name'] if label.is_a?(Hash)
+
+        label.to_s
+      end
+
+      # @return [Array<PlanMyStuff::Comment>]
+      def load_comments
+        Comment.list(issue: self)
+      end
+  end
+end

data/lib/plan_my_stuff/issue_metadata.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class IssueMetadata < BaseMetadata
+    # @return [Time, nil] first support action timestamp, nil until set
+    attr_accessor :responded_at
+    # @return [String, nil] user-facing URL in the consuming app
+    attr_accessor :issues_url
+    # @return [Boolean] whether this issue appears on the priority dashboard
+    attr_accessor :priority_list
+    # @return [Integer] sort order on priority dashboard (-1 = unranked)
+    attr_accessor :priority_list_priority
+    # @return [Array<Integer>] user IDs of non-support users allowed to view internal comments
+    attr_accessor :visibility_allowlist
+
+    class << self
+      # Builds an IssueMetadata from a parsed hash (e.g. from MetadataParser)
+      #
+      # @param hash [Hash]
+      #
+      # @return [IssueMetadata]
+      #
+      def from_hash(hash)
+        metadata = new
+        apply_common_from_hash(metadata, hash)
+
+        metadata.responded_at = parse_time(hash[:responded_at])
+        metadata.issues_url = hash[:issues_url]
+        metadata.priority_list = hash.fetch(:priority_list, false)
+        metadata.priority_list_priority = hash.fetch(:priority_list_priority, -1)
+        metadata.visibility_allowlist = Array.wrap(hash[:visibility_allowlist])
+
+        metadata
+      end
+
+      # Builds a new IssueMetadata for issue creation, auto-filling gem defaults
+      #
+      # @param user [Object, Integer] user object or user_id
+      # @param custom_fields [Hash] app-defined field values
+      #
+      # @return [IssueMetadata]
+      #
+      def build(user:, visibility: 'public', custom_fields: {})
+        metadata = new
+        apply_common_build(metadata, user: user, visibility: visibility, custom_fields_data: custom_fields)
+
+        metadata.responded_at = nil
+        metadata.issues_url = build_issues_url(PlanMyStuff.configuration)
+        metadata.priority_list = false
+        metadata.priority_list_priority = -1
+        metadata.visibility_allowlist = []
+
+        metadata
+      end
+
+      private
+
+        # @return [String, nil]
+        def build_issues_url(config)
+          return if config.issues_url_prefix.nil?
+
+          config.issues_url_prefix.to_s
+        end
+    end
+
+    def initialize
+      super
+      @priority_list = false
+      @priority_list_priority = -1
+      @visibility_allowlist = []
+    end
+
+    # @return [Boolean]
+    def priority_list?
+      !!priority_list
+    end
+
+    # @return [Boolean]
+    def responded?
+      !responded_at.nil?
+    end
+
+    # Checks whether a user can see this issue's internal content.
+    # Public issues are always visible. Internal issues are visible if the
+    # user is support staff or their ID is in the visibility_allowlist.
+    #
+    # @param user [Object, Integer] user object or user_id
+    #
+    # @return [Boolean]
+    #
+    def visible_to?(user)
+      return true if public?
+
+      resolved = UserResolver.resolve(user)
+      return true if UserResolver.support?(resolved)
+
+      visibility_allowlist.include?(UserResolver.user_id(resolved))
+    end
+
+    # @return [Hash]
+    def to_h
+      super.merge(
+        responded_at: format_time(responded_at),
+        issues_url: issues_url,
+        priority_list: priority_list,
+        priority_list_priority: priority_list_priority,
+        visibility_allowlist: visibility_allowlist,
+      )
+    end
+  end
+end

data/lib/plan_my_stuff/label.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Wraps a GitHub label with a reference to its parent issue.
+  # Class methods provide the public API for add/remove operations.
+  class Label < PlanMyStuff::ApplicationRecord
+    # @return [String] label name
+    attr_accessor :name
+    # @return [PlanMyStuff::Issue] parent issue
+    attr_accessor :issue
+
+    class << self
+      # Adds labels to a GitHub issue.
+      #
+      # @param issue [PlanMyStuff::Issue] parent issue
+      # @param labels [Array<String>]
+      #
+      # @return [Array<PlanMyStuff::Label>]
+      #
+      def add(issue:, labels:)
+        result = PlanMyStuff.client.rest(
+          :add_labels_to_an_issue, issue.repo, issue.number, labels,
+        )
+
+        result.map { |gh_label| build(gh_label, issue: issue) }
+      end
+
+      # Removes labels from a GitHub issue.
+      #
+      # @param issue [PlanMyStuff::Issue] parent issue
+      # @param labels [Array<String>]
+      #
+      # @return [Array<Array<PlanMyStuff::Label>>] results of each removal
+      #
+      def remove(issue:, labels:)
+        Array.wrap(labels).map do |label|
+          result = PlanMyStuff.client.rest(:remove_label, issue.repo, issue.number, label)
+          result.map { |gh_label| build(gh_label, issue: issue) }
+        end
+      end
+
+      private
+
+        # Hydrates a Label from a GitHub API response.
+        #
+        # @param github_label [Object] Octokit label response
+        # @param issue [PlanMyStuff::Issue] parent issue
+        #
+        # @return [PlanMyStuff::Label]
+        #
+        def build(github_label, issue:)
+          label_name = github_label.respond_to?(:name) ? github_label.name : github_label[:name]
+          label = new(name: label_name, issue: issue)
+          label.instance_variable_set(:@persisted, true)
+          label
+        end
+    end
+  end
+end