plan_my_stuff 0.3.0 → 0.5.0

data/lib/plan_my_stuff/issue_metadata.rb

@@ -12,6 +12,30 @@ module PlanMyStuff
     attr_accessor :priority_list_priority
     # @return [Array<Integer>] user IDs of non-support users allowed to view internal comments
     attr_accessor :visibility_allowlist
+    # @return [String, nil] merged PR commit SHA for release tracking
+    attr_accessor :commit_sha
+    # @return [Boolean] whether to auto-complete on deployment (default: true)
+    attr_accessor :auto_complete
+    # @return [Array<PlanMyStuff::Link>] metadata-backed issue relationships.
+    #   Only +:related+ links live here; native relationships (blocking,
+    #   parent, sub_ticket, duplicate_of) live on GitHub.
+    attr_accessor :links
+    # @return [Array<PlanMyStuff::Approval>] manager approvals required on
+    #   this issue. See +Issue.request_approvals!+ and +Issue#fully_approved?+.
+    attr_accessor :approvals
+    # @return [Time, nil] when the issue entered "waiting on user reply" state
+    attr_accessor :waiting_on_user_at
+    # @return [Time, nil] when the issue entered "waiting on approval" state
+    attr_accessor :waiting_on_approval_at
+    # @return [Time, nil] when the next reminder event should fire for this issue
+    attr_accessor :next_reminder_at
+    # @return [Array<Integer>, nil] per-issue override of +config.reminder_days+;
+    #   applies to both waiting kinds
+    attr_accessor :reminder_days
+    # @return [Boolean] whether this issue was auto-closed by the inactivity sweep
+    attr_accessor :closed_by_inactivity
+    # @return [Time, nil] when the archive sweep tagged this issue as archived
+    attr_accessor :archived_at
 
     class << self
       # Builds an IssueMetadata from a parsed hash (e.g. from MetadataParser)
@@ -29,6 +53,16 @@ module PlanMyStuff
         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.commit_sha = hash[:commit_sha]
+        metadata.auto_complete = hash.fetch(:auto_complete, true)
+        metadata.links = normalize_links(hash[:links])
+        metadata.approvals = normalize_approvals(hash[:approvals])
+        metadata.waiting_on_user_at = parse_time(hash[:waiting_on_user_at])
+        metadata.waiting_on_approval_at = parse_time(hash[:waiting_on_approval_at])
+        metadata.next_reminder_at = parse_time(hash[:next_reminder_at])
+        metadata.reminder_days = normalize_reminder_days(hash[:reminder_days])
+        metadata.closed_by_inactivity = hash.fetch(:closed_by_inactivity, false)
+        metadata.archived_at = parse_time(hash[:archived_at])
 
         metadata
       end
@@ -55,6 +89,16 @@ module PlanMyStuff
         metadata.priority_list = false
         metadata.priority_list_priority = -1
         metadata.visibility_allowlist = []
+        metadata.commit_sha = nil
+        metadata.auto_complete = true
+        metadata.links = []
+        metadata.approvals = []
+        metadata.waiting_on_user_at = nil
+        metadata.waiting_on_approval_at = nil
+        metadata.next_reminder_at = nil
+        metadata.reminder_days = nil
+        metadata.closed_by_inactivity = false
+        metadata.archived_at = nil
 
         metadata
       end
@@ -67,6 +111,60 @@ module PlanMyStuff
 
           config.issues_url_prefix.to_s
         end
+
+        # Builds a +PlanMyStuff::Link+ from each parsed entry. Malformed
+        # entries (wrong shape, missing fields, invalid values) are
+        # silently dropped so a single bad entry doesn't crash
+        # +Issue.find+ for an otherwise healthy issue.
+        #
+        # @param raw [Array, nil]
+        #
+        # @return [Array<PlanMyStuff::Link>]
+        #
+        def normalize_links(raw)
+          Array.wrap(raw).filter_map do |entry|
+            PlanMyStuff::Link.build(entry)
+          rescue ActiveModel::ValidationError, ArgumentError
+            next
+          end
+        end
+
+        # Builds a +PlanMyStuff::Approval+ from each parsed entry.
+        # Malformed entries (wrong shape, missing fields, invalid values,
+        # unknown attributes) are silently dropped so a single bad entry
+        # doesn't crash +Issue.find+ for an otherwise healthy issue.
+        #
+        # @param raw [Array, nil]
+        #
+        # @return [Array<PlanMyStuff::Approval>]
+        #
+        def normalize_approvals(raw)
+          Array.wrap(raw).filter_map do |entry|
+            approval = PlanMyStuff::Approval.new(entry.transform_keys(&:to_sym))
+            approval.validate!
+            approval
+          rescue ActiveModel::ValidationError, ArgumentError, NoMethodError
+            next
+          end
+        end
+
+        # Normalizes a raw +reminder_days+ value from parsed metadata.
+        # Returns +nil+ when absent so callers can fall back to config;
+        # otherwise returns the array with non-integer entries dropped.
+        #
+        # @param raw [Object]
+        #
+        # @return [Array<Integer>, nil]
+        #
+        def normalize_reminder_days(raw)
+          return if raw.nil?
+
+          Array.wrap(raw).filter_map do |entry|
+            Integer(entry)
+          rescue ArgumentError, TypeError
+            next
+          end
+        end
     end
 
     def initialize
@@ -74,6 +172,20 @@ module PlanMyStuff
       @priority_list = false
       @priority_list_priority = -1
       @visibility_allowlist = []
+      @auto_complete = true
+      @links = []
+      @approvals = []
+      @waiting_on_user_at = nil
+      @waiting_on_approval_at = nil
+      @next_reminder_at = nil
+      @reminder_days = nil
+      @closed_by_inactivity = false
+      @archived_at = nil
+    end
+
+    # @return [Boolean]
+    def auto_complete?
+      !!auto_complete
     end
 
     # @return [Boolean]
@@ -111,6 +223,16 @@ module PlanMyStuff
         priority_list: priority_list,
         priority_list_priority: priority_list_priority,
         visibility_allowlist: visibility_allowlist,
+        commit_sha: commit_sha,
+        auto_complete: auto_complete,
+        links: links.map(&:to_h),
+        approvals: approvals.map(&:to_h),
+        waiting_on_user_at: format_time(waiting_on_user_at),
+        waiting_on_approval_at: format_time(waiting_on_approval_at),
+        next_reminder_at: format_time(next_reminder_at),
+        reminder_days: reminder_days,
+        closed_by_inactivity: closed_by_inactivity,
+        archived_at: format_time(archived_at),
       )
     end
   end

data/lib/plan_my_stuff/label.rb

@@ -4,43 +4,104 @@ 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
+    # @return [String, nil]
+    attribute :name, :string
+    # @return [PlanMyStuff::Issue, nil]
+    attribute :issue
 
     class << self
       # Adds labels to a GitHub issue.
       #
       # @param issue [PlanMyStuff::Issue] parent issue
       # @param labels [Array<String>]
+      # @param user [Object, nil] actor for the notification event
       #
       # @return [Array<PlanMyStuff::Label>]
       #
-      def add(issue:, labels:)
+      def add(issue:, labels:, user: nil)
+        label_names = Array.wrap(labels)
+
         result = PlanMyStuff.client.rest(
-          :add_labels_to_an_issue, issue.repo, issue.number, labels,
+          :add_labels_to_an_issue, issue.repo, issue.number, label_names,
+        )
+
+        PMS::Cache.delete_issue(issue.repo, issue.number)
+
+        PlanMyStuff::Notifications.instrument(
+          'label.added', issue, user: user, labels: label_names,
         )
 
         result.map { |gh_label| build(gh_label, issue: issue) }
       end
 
+      # Ensures a label exists on the given repo, creating it if missing.
+      # Idempotent: a 404 from +label+ triggers creation; a 422 from
+      # +add_label+ (concurrent-creation race) is treated as success.
+      #
+      # @param repo [String, Symbol] repo name or key
+      # @param name [String] label name
+      # @param color [String] hex color without +#+
+      # @param description [String, nil]
+      #
+      # @return [void]
+      #
+      def ensure!(repo:, name:, color: 'fbca04', description: nil)
+        client = PlanMyStuff.client
+        client.rest(:label, repo, name)
+      rescue PlanMyStuff::APIError => e
+        raise unless e.status == 404
+
+        create_label(client, repo, name, color, description)
+      end
+
       # Removes labels from a GitHub issue.
       #
       # @param issue [PlanMyStuff::Issue] parent issue
       # @param labels [Array<String>]
+      # @param user [Object, nil] actor for the notification event
       #
       # @return [Array<Array<PlanMyStuff::Label>>] results of each removal
       #
-      def remove(issue:, labels:)
-        Array.wrap(labels).map do |label|
+      def remove(issue:, labels:, user: nil)
+        label_names = Array.wrap(labels)
+
+        results = label_names.map do |label|
           result = PlanMyStuff.client.rest(:remove_label, issue.repo, issue.number, label)
           result.map { |gh_label| build(gh_label, issue: issue) }
         end
+
+        PMS::Cache.delete_issue(issue.repo, issue.number)
+
+        PlanMyStuff::Notifications.instrument(
+          'label.removed', issue, user: user, labels: label_names,
+        )
+
+        results
       end
 
       private
 
+        # Creates a label, tolerating the 422 "already exists" race that
+        # occurs when a concurrent ensure! slipped in between our 404 read
+        # and this write.
+        #
+        # @param client [PlanMyStuff::Client]
+        # @param repo [String, Symbol]
+        # @param name [String]
+        # @param color [String]
+        # @param description [String, nil]
+        #
+        # @return [void]
+        #
+        def create_label(client, repo, name, color, description)
+          options = {}
+          options[:description] = description if description
+
+          client.rest(:add_label, repo, name, color, **options)
+        rescue PlanMyStuff::APIError => e
+          raise unless e.status == 422
+        end
+
         # Hydrates a Label from a GitHub API response.
         #
         # @param github_label [Object] Octokit label response
@@ -49,11 +110,21 @@ module PlanMyStuff
         # @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 = new(name: read_field(github_label, :name), issue: issue)
+          label.instance_variable_set(:@github_response, github_label)
+          label.__send__(:persisted!)
           label
         end
     end
+
+    # Serializes the label to a JSON-safe hash, excluding the back-reference
+    # to the parent issue to prevent recursive serialization cycles.
+    #
+    # @return [Hash]
+    #
+    def as_json(options = {})
+      merged_except = Array.wrap(options[:except]) + ['issue']
+      super(options.merge(except: merged_except)).merge('issue_number' => issue&.number)
+    end
   end
 end

data/lib/plan_my_stuff/link.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+module PlanMyStuff
+  # Value object representing a typed relationship between two issues.
+  # Built by +Issue#add_related!+, +#add_blocker!+, +#add_sub_issue!+,
+  # +#set_parent!+, and +#mark_duplicate!+; also returned from their
+  # +remove_*+ counterparts so callers can render activity-log lines
+  # like +"Added parent issue: owner/repo#42"+.
+  #
+  # Metadata-backed types live in +IssueMetadata#links+; native types
+  # are routed through GitHub APIs and never persisted in our metadata.
+  class Link
+    METADATA_TYPES = %w[related].freeze
+    NATIVE_TYPES = %w[blocking blocked_by parent sub_ticket duplicate_of].freeze
+    ALL_TYPES = (METADATA_TYPES + NATIVE_TYPES).freeze
+
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Serializers::JSON
+
+    # @return [String] one of ALL_TYPES
+    attribute :type, :string
+    # @return [Integer] target issue's GitHub issue number
+    attribute :issue_number, :integer
+    # @return [String] full "owner/name" path of the target issue's repo
+    attribute :repo, :string
+
+    validates :type, presence: true, inclusion: { in: ALL_TYPES }
+    validates :issue_number, presence: true, numericality: { greater_than: 0, only_integer: true }
+    validates :repo, presence: true
+
+    class << self
+      # Builds and validates a +Link+ from an +Issue+-like object, another
+      # +Link+, or a hash. +type:+ fills in when the input does not carry
+      # one; +source_repo+ fills in when the hash input does not carry
+      # one. Raises +ActiveModel::ValidationError+ on missing/invalid
+      # fields, +ArgumentError+ when +input+ is an unsupported shape.
+      #
+      # @param input [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
+      # @param type [String, Symbol, nil]
+      # @param source_repo [String, PlanMyStuff::Repo, nil]
+      #
+      # @return [PlanMyStuff::Link]
+      #
+      def build(input, type: nil, source_repo: nil)
+        return input if input.is_a?(PlanMyStuff::Link)
+
+        link =
+          if input.is_a?(Hash)
+            build_from_hash(input, type: type, source_repo: source_repo)
+          else
+            build_from_issue_like(input, type: type)
+          end
+
+        link.validate!
+        link
+      end
+
+      private
+
+        # @return [PlanMyStuff::Link]
+        def build_from_issue_like(input, type:)
+          if !input.respond_to?(:number) || !input.respond_to?(:repo)
+            raise(ArgumentError, "Cannot build Link from #{input.class}")
+          end
+
+          new(
+            type: type&.to_s,
+            issue_number: input.number,
+            repo: repo_string(input.repo),
+          )
+        end
+
+        # @return [PlanMyStuff::Link]
+        def build_from_hash(hash, type:, source_repo:)
+          data = hash.transform_keys(&:to_sym)
+          new(
+            type: (data[:type] || type)&.to_s,
+            issue_number: data[:issue_number],
+            repo: repo_string(data[:repo] || source_repo),
+          )
+        end
+
+        # @return [String, nil]
+        def repo_string(value)
+          return if value.nil?
+          return value.full_name if value.is_a?(PlanMyStuff::Repo)
+
+          value.to_s
+        end
+    end
+
+    # @return [String] e.g. "owner/repo#42"
+    def to_s
+      "#{repo}##{issue_number}"
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        type: type,
+        issue_number: issue_number,
+        repo: repo,
+      }
+    end
+
+    # @param other_repo [String, PlanMyStuff::Repo, nil]
+    #
+    # @return [Boolean]
+    #
+    def same_repo?(other_repo)
+      return false if other_repo.nil?
+
+      repo == self.class.__send__(:repo_string, other_repo)
+    end
+
+    # Lazy-fetches and memoizes the target +Issue+.
+    #
+    # @return [PlanMyStuff::Issue]
+    #
+    def issue
+      @issue ||= PlanMyStuff::Issue.find(issue_number, repo: repo)
+    end
+
+    # @param other [Object]
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      return false unless other.is_a?(PlanMyStuff::Link)
+
+      type == other.type && issue_number == other.issue_number && repo == other.repo
+    end
+
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [type, issue_number, repo].hash
+    end
+  end
+end

data/lib/plan_my_stuff/notifications.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module PlanMyStuff
+  # Central instrumentation helper. Domain classes call
+  # +PlanMyStuff::Notifications.instrument+ at mutation points so
+  # consuming apps can subscribe for email, webhooks, Slack, etc.
+  #
+  # Events are fired under the +plan_my_stuff.<event>+ namespace via
+  # +ActiveSupport::Notifications+. Subscribers run synchronously.
+  #
+  module Notifications
+    module_function
+
+    EVENT_PREFIX = 'plan_my_stuff'
+    SKIPPED_LOG_KEYS = %i[user timestamp visibility visibility_allowlist].freeze
+
+    # Fires +plan_my_stuff.<event>+ with a normalized payload.
+    #
+    # @param event [String] e.g. +'issue.created'+
+    # @param resource [Object] domain object (+Issue+, +Comment+, +ProjectItem+, ...)
+    # @param user [Object, nil] explicit actor; falls back to +config.current_user+
+    # @param extra [Hash] additional payload entries (+changes:+, +labels:+, +user_ids:+, ...)
+    #
+    # @return [void]
+    #
+    def instrument(event, resource, user: nil, **extra)
+      actor = user || resolve_current_user
+      payload = build_payload(resource, actor, extra)
+      log(event, payload)
+      ActiveSupport::Notifications.instrument("#{EVENT_PREFIX}.#{event}", payload)
+    end
+
+    # Invokes +config.current_user+ if it responds to +call+.
+    #
+    # @return [Object, nil]
+    #
+    def resolve_current_user
+      resolver = PlanMyStuff.configuration.current_user
+      return if resolver.nil?
+
+      resolver.respond_to?(:call) ? resolver.call : resolver
+    end
+
+    # Builds the payload hash for an event.
+    #
+    # @param resource [Object]
+    # @param actor [Object, nil]
+    # @param extra [Hash]
+    #
+    # @return [Hash]
+    #
+    def build_payload(resource, actor, extra)
+      payload = {
+        infer_resource_key(resource) => resource,
+        :user => actor,
+        :timestamp => Time.current,
+      }
+      payload.merge!(visibility_fields(resource))
+      payload.merge(extra)
+    end
+
+    # Maps a resource object to its payload key.
+    #
+    # @param resource [Object]
+    #
+    # @return [Symbol]
+    #
+    def infer_resource_key(resource)
+      case resource
+      when PlanMyStuff::Issue then :issue
+      when PlanMyStuff::Comment then :comment
+      when PlanMyStuff::BaseProjectItem then :project_item
+      else :resource
+      end
+    end
+
+    # Extracts visibility + allowlist from +Issue+/+Comment+ resources.
+    # Returns an empty hash for resources without visibility.
+    #
+    # @param resource [Object]
+    #
+    # @return [Hash]
+    #
+    def visibility_fields(resource)
+      case resource
+      when PlanMyStuff::Issue
+        {
+          visibility: resource.metadata.visibility,
+          visibility_allowlist: Array.wrap(resource.metadata.visibility_allowlist),
+        }
+      when PlanMyStuff::Comment
+        parent_allowlist = resource.issue ? resource.issue.metadata.visibility_allowlist : []
+        {
+          visibility: resource.visibility&.to_s,
+          visibility_allowlist: Array.wrap(parent_allowlist),
+        }
+      else
+        {}
+      end
+    end
+
+    # Emits a debug log line for the event. No-op when no logger is
+    # available (e.g. outside Rails).
+    #
+    # @param event [String]
+    # @param payload [Hash]
+    #
+    # @return [void]
+    #
+    def log(event, payload)
+      logger = rails_logger
+      return if logger.nil?
+
+      logger.debug { "[PMS] #{EVENT_PREFIX}.#{event} #{log_fields(payload)}" }
+    end
+
+    # @return [Logger, nil]
+    def rails_logger
+      return unless defined?(Rails)
+      return unless Rails.respond_to?(:logger)
+
+      Rails.logger
+    end
+
+    # @param payload [Hash]
+    #
+    # @return [String]
+    #
+    def log_fields(payload)
+      fields = []
+      fields << "user=#{payload[:user].inspect}" if payload.key?(:user)
+      payload.each do |key, value|
+        next if SKIPPED_LOG_KEYS.include?(key)
+
+        fields << "#{key}=#{value.inspect}"
+      end
+      fields.join(' ')
+    end
+  end
+end

data/lib/plan_my_stuff/pipeline/issue_linker.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Pipeline
+    # Resolves linked issues from pull request payloads and finds their
+    # corresponding ProjectItems in the pipeline project.
+    #
+    # Uses +module_function+ pattern (matches +MetadataParser+, +Pipeline+).
+    #
+    module IssueLinker
+      module_function
+
+      # Regex matching GitHub closing keywords in PR bodies.
+      # Matches all nine variants: close/closes/closed, fix/fixes/fixed,
+      # resolve/resolves/resolved (case-insensitive).
+      CLOSING_KEYWORD_PATTERN = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)\b/i
+
+      # Extracts issue numbers from a PR payload by parsing the PR body
+      # and commit messages for GitHub closing keywords (close/closes/closed,
+      # fix/fixes/fixed, resolve/resolves/resolved).
+      #
+      # @param pr_payload [Hash] parsed PR webhook payload (expects +:body+ or +"body"+ key)
+      # @param commit_messages [Array<String>] commit messages to scan (default: [])
+      #
+      # @return [Array<Integer>] referenced issue numbers (empty if none found)
+      #
+      def extract_issue_numbers(pr_payload, commit_messages: [])
+        texts = []
+
+        body = pr_payload[:body] || pr_payload['body']
+        texts << body if body.present?
+
+        Array.wrap(commit_messages).each do |message|
+          texts << message if message.present?
+        end
+
+        return [] if texts.empty?
+
+        matches = texts.join("\n").scan(CLOSING_KEYWORD_PATTERN).flatten
+        matches.map!(&:to_i)
+        matches.uniq!
+        matches
+      end
+
+      # Finds the ProjectItem in the pipeline project that matches the given
+      # issue number. Loads the full project and iterates its items.
+      #
+      # @param issue_number [Integer] issue number to find
+      # @param repo [Symbol, String, nil] unused, reserved for future multi-repo support
+      # @param project_number [Integer, nil] pipeline project number
+      #
+      # @return [PlanMyStuff::ProjectItem, nil] matching item, or nil if not found
+      #
+      def find_project_item(issue_number, _repo: nil, project_number: nil)
+        number = PlanMyStuff::Pipeline.resolve_pipeline_project_number(project_number)
+        project = PlanMyStuff::Project.find(number)
+
+        project.items.find { |item| item.number == issue_number }
+      end
+    end
+  end
+end

data/lib/plan_my_stuff/pipeline/status.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Pipeline
+    # Canonical pipeline status constants.
+    #
+    # Each constant holds the human-readable status name that maps to a
+    # GitHub Projects V2 single-select field value.  Consuming apps can
+    # override display names via +PlanMyStuff.configuration.pipeline_statuses+
+    # but the canonical names here remain the internal identifiers.
+    #
+    module Status
+      SUBMITTED = 'Submitted'
+      STARTED = 'Started'
+      IN_REVIEW = 'In Review'
+      TESTING = 'Testing'
+      READY_FOR_RELEASE = 'Ready for Release'
+      RELEASE_IN_PROGRESS = 'Release in Progress'
+      COMPLETED = 'Completed'
+
+      # All statuses in pipeline order (frozen).
+      ALL = [
+        SUBMITTED,
+        STARTED,
+        IN_REVIEW,
+        TESTING,
+        READY_FOR_RELEASE,
+        RELEASE_IN_PROGRESS,
+        COMPLETED,
+      ].freeze
+
+      # Converts a canonical status name to a snake_case key suitable for
+      # notification event names.
+      #
+      # @param canonical [String] one of the canonical status names
+      #
+      # @return [String] snake_case key (e.g. +"ready_for_release"+)
+      #
+      def self.key_for(canonical)
+        canonical.downcase.tr(' ', '_')
+      end
+    end
+  end
+end