plan_my_stuff 0.1.0 → 1.0.0

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,40 @@
+# 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
+      STARTED = 'Started'
+      IN_REVIEW = 'In Review'
+      READY_FOR_RELEASE = 'Ready for Release'
+      RELEASE_IN_PROGRESS = 'Release in Progress'
+      COMPLETED = 'Completed'
+
+      # All statuses in pipeline order (frozen).
+      ALL = [
+        STARTED,
+        IN_REVIEW,
+        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

data/lib/plan_my_stuff/pipeline/testing.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Pipeline
+    # Canonical names for the +Testing+ single-select custom field on the
+    # pipeline project. The field tracks testing progress orthogonally to
+    # the +Status+ field (testing can run alongside +In Review+).
+    #
+    # Consuming apps can override the field name via
+    # +PlanMyStuff.configuration.pipeline_testing_field_name+ and the
+    # option labels via +PlanMyStuff.configuration.pipeline_testing_values+.
+    # The canonical names here remain the internal identifiers.
+    #
+    module Testing
+      FIELD_NAME = 'Testing'
+
+      VALUES = {
+        active: 'Testing',
+        inactive: 'Not testing',
+      }.freeze
+    end
+  end
+end

data/lib/plan_my_stuff/pipeline.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # High-level orchestration layer for the release pipeline.
+  #
+  # Named lifecycle methods wrap the low-level +ProjectItem.move_to!+ calls, resolve configurable status aliases, and
+  # fire +ActiveSupport::Notifications+ events on every transition.
+  #
+  # No transition enforcement -- any status can move to any other.
+  #
+  module Pipeline
+    module_function
+
+    # Raises +PlanMyStuff::PendingApprovalsError+ when +issue+ has pending manager approvals. No-op for +nil+ issues or
+    # issues that either have no approvers required or are fully approved.
+    #
+    # Called at the top of every forward transition (+take!+, +mark_in_review!+, +request_testing!+,
+    # +mark_ready_for_release!+). Batch / CI-driven transitions (+start_deployment!+, +complete_deployment!+) and
+    # reverse transitions (+remove!+) are intentionally NOT gated -- earlier forward transitions already required
+    # approval, and gating batch/automated paths would abort entire deploys on a single approval revoke.
+    #
+    # @raise [PlanMyStuff::PendingApprovalsError] when +issue+ has pending approvals
+    #
+    # @param issue [PlanMyStuff::Issue, nil]
+    #
+    # @return [void]
+    #
+    def guard_approvals!(issue)
+      return if issue.nil?
+
+      return unless issue.approvals_required?
+
+      return if issue.fully_approved?
+
+      raise(PlanMyStuff::PendingApprovalsError.new(
+        issue: issue,
+        pending_count: issue.pending_approvals.count,
+      ))
+    end
+
+    # Resolves a canonical status name to its configured display alias, falling back to the canonical name when no
+    # alias is configured.
+    #
+    # @param canonical [String] one of the +Pipeline::Status+ constants
+    #
+    # @return [String]
+    #
+    def resolve_status_name(canonical)
+      PlanMyStuff.configuration.pipeline_statuses.fetch(canonical, canonical)
+    end
+
+    # Fires a +pipeline_<event>.plan_my_stuff+ notification.
+    #
+    # When +event+ is a canonical +Pipeline::Status+ name, the event key is derived via +Status.key_for+ and the
+    # canonical status is added to the payload as +:status+. Otherwise +event+ is used verbatim as the suffix (e.g.
+    # +"removed"+, +"removed_late"+, +"testing"+).
+    #
+    # +resource+ is normally a single project item (payload carries +:issue_number+). Pass an +Array+ for a batch
+    # event (e.g. the deployment-completed sweep) and the payload instead carries +:issue_numbers+ -- the linked
+    # number of every item.
+    #
+    # @param event [String] status name or literal event suffix
+    # @param resource [PlanMyStuff::BaseProjectItem, Array<PlanMyStuff::BaseProjectItem>] item or batch of items
+    # @param extra [Hash] additional payload entries
+    #
+    # @return [void]
+    #
+    def instrument(event, resource, **extra)
+      extra_to_use = { **extra }
+      event_to_use = event
+      if PlanMyStuff::Pipeline::Status::ALL.include?(event_to_use)
+        extra_to_use = { status: event, **extra_to_use }
+        event_to_use = PlanMyStuff::Pipeline::Status.key_for(event_to_use)
+      end
+
+      number_fields =
+        if resource.is_a?(Array)
+          { issue_numbers: resource.map(&:number) }
+        else
+          { issue_number: resource.number }
+        end
+
+      PlanMyStuff::Notifications.instrument(
+        "pipeline_#{event_to_use}",
+        resource,
+        **number_fields,
+        **extra_to_use,
+      )
+    end
+
+    # Returns the pipeline project number from the explicit argument, +pipeline_project_number+, or
+    # +default_project_number+.
+    #
+    # @raise [ArgumentError] if no project number can be resolved
+    #
+    # @param project_number [Integer, nil]
+    #
+    # @return [Integer]
+    #
+    def resolve_pipeline_project_number!(project_number = nil)
+      config = PlanMyStuff.configuration
+      result = project_number || config.pipeline_project_number || config.default_project_number
+
+      raise(ArgumentError, 'No pipeline project number configured') if result.nil?
+
+      result
+    end
+
+    # Removes a project item from the pipeline project entirely. Captures the prior status before deletion so
+    # subscribers can decide whether the removal happened late in the lifecycle.
+    #
+    # Always fires +pipeline_removed.plan_my_stuff+. Additionally fires +pipeline_removed_late.plan_my_stuff+ when
+    # +prior_status+ is past "Started" (i.e. anything other than "Started", accounting for configured status aliases).
+    # +nil+ status is treated as not-late.
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    #
+    # @return [String, nil] the deleted item ID, or nil if already destroyed
+    #
+    def remove!(project_item)
+      prior_status = project_item.status
+      result = project_item.destroy!
+
+      instrument('removed', project_item, prior_status: prior_status)
+      instrument('removed_late', project_item, prior_status: prior_status) if late_removal?(prior_status)
+
+      result
+    end
+
+    # Returns true when +prior_status+ is past "Started" in the pipeline. Honors configured status aliases. +nil+ is
+    # treated as not-late.
+    #
+    # @param prior_status [String, nil]
+    #
+    # @return [Boolean]
+    #
+    def late_removal?(prior_status)
+      return false if prior_status.nil?
+
+      started = resolve_status_name(PlanMyStuff::Pipeline::Status::STARTED)
+      prior_status != started
+    end
+
+    # Returns true when +project_item+ is at a release-cycle status ("Ready for Release", "Release in Progress", or
+    # "Completed"). Honors configured status aliases.
+    #
+    # Used to lock items against webhook-driven removals once they enter the release path -- a stray unassign should
+    # not yank an item out of "Release in Progress".
+    #
+    # @param project_item [PlanMyStuff::BaseProjectItem]
+    #
+    # @return [Boolean]
+    #
+    def release_cycle_locked?(project_item)
+      locked_statuses = [
+        resolve_status_name(PlanMyStuff::Pipeline::Status::READY_FOR_RELEASE),
+        resolve_status_name(PlanMyStuff::Pipeline::Status::RELEASE_IN_PROGRESS),
+        resolve_status_name(PlanMyStuff::Pipeline::Status::COMPLETED),
+      ]
+
+      locked_statuses.include?(project_item.status)
+    end
+
+    # Moves a project item to "Started". When +user+ is a support user, also stamps +metadata.responded_at+ on the
+    # issue via +Issue#mark_responded!+ (a no-op if it's already responded to / not a PMS issue).
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    # @param user [Object, nil] actor forwarded to the +pipeline_started.plan_my_stuff+ payload
+    #
+    # @return [Hash] mutation result
+    #
+    def take!(project_item, user: nil)
+      guard_approvals!(project_item&.issue)
+      status = resolve_status_name(PlanMyStuff::Pipeline::Status::STARTED)
+      result = project_item.move_to!(status)
+
+      project_item.issue.mark_responded!(user) if user.present?
+
+      instrument(PlanMyStuff::Pipeline::Status::STARTED, project_item, user: user)
+      result
+    end
+
+    # Moves a project item to "In Review".
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    #
+    # @return [Hash] mutation result
+    #
+    def mark_in_review!(project_item)
+      guard_approvals!(project_item&.issue)
+      status = resolve_status_name(PlanMyStuff::Pipeline::Status::IN_REVIEW)
+      result = project_item.move_to!(status)
+
+      instrument(PlanMyStuff::Pipeline::Status::IN_REVIEW, project_item)
+      result
+    end
+
+    # Marks a project item as in testing by setting the +Testing+ custom single-select field to its active value. Does
+    # NOT change the item's +Status+ -- testing runs orthogonally to +In Review+.
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    # @param user [Object, nil] actor forwarded to the +pipeline_testing.plan_my_stuff+ payload
+    #
+    # @return [Hash] mutation result
+    #
+    def request_testing!(project_item, user: nil)
+      guard_approvals!(project_item&.issue)
+      field_name = PlanMyStuff.configuration.pipeline_testing_field_name
+      value = PlanMyStuff.configuration.pipeline_testing_values.fetch(:active)
+      result = project_item.update_single_select_field!(field_name, value)
+
+      instrument('testing', project_item, field_name: field_name, value: value, user: user)
+
+      result
+    end
+
+    # Reverses +request_testing!+ by flipping the +Testing+ custom single-select field back to its inactive value.
+    # Not approval-gated -- the forward transition (+request_testing!+) was already gated, so clearing should always
+    # succeed (matches +remove!+).
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    # @param user [Object, nil] actor forwarded to the +pipeline_testing_cleared.plan_my_stuff+ payload
+    #
+    # @return [Hash] mutation result
+    #
+    def clear_testing!(project_item, user: nil)
+      field_name = PlanMyStuff.configuration.pipeline_testing_field_name
+      value = PlanMyStuff.configuration.pipeline_testing_values.fetch(:inactive)
+      result = project_item.update_single_select_field!(field_name, value)
+
+      instrument('testing_cleared', project_item, field_name: field_name, value: value, user: user)
+
+      result
+    end
+
+    # Moves a project item to "Ready for Release".
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    #
+    # @return [Hash] mutation result
+    #
+    def mark_ready_for_release!(project_item)
+      guard_approvals!(project_item&.issue)
+      status = resolve_status_name(PlanMyStuff::Pipeline::Status::READY_FOR_RELEASE)
+      result = project_item.move_to!(status)
+
+      instrument(PlanMyStuff::Pipeline::Status::READY_FOR_RELEASE, project_item)
+      result
+    end
+
+    # Finds ALL items at "Ready for Release" in the pipeline project and moves each to "Release in Progress". Fires an
+    # event per item.
+    #
+    # When +commit_sha+ is given (the merge_commit_sha of the PR into +production+), it is stamped onto every moved
+    # item's linked issue metadata. +AwsController#handle_deployment_completed+ later matches this sha against the
+    # configured +production_commit_sha+ to decide which items to auto-complete, so this is the only commit sha in the
+    # release cycle that matters.
+    #
+    # @param project_number [Integer, nil]
+    # @param commit_sha [String, nil]
+    #
+    # @return [Array<PlanMyStuff::ProjectItem>]
+    #
+    def start_deployment!(project_number: nil, commit_sha: nil)
+      number = resolve_pipeline_project_number!(project_number)
+      project = PlanMyStuff::Project.find(number)
+
+      ready_status = resolve_status_name(PlanMyStuff::Pipeline::Status::READY_FOR_RELEASE)
+      in_progress_status = resolve_status_name(PlanMyStuff::Pipeline::Status::RELEASE_IN_PROGRESS)
+
+      items = project.items.select { |item| item.status == ready_status }
+
+      items.each do |item|
+        if commit_sha.present?
+          issue = item.issue
+          issue.metadata.commit_sha = commit_sha
+          issue.save!
+        end
+
+        item.move_to!(in_progress_status)
+        instrument(PlanMyStuff::Pipeline::Status::RELEASE_IN_PROGRESS, item, commit_sha: commit_sha)
+      end
+
+      items
+    end
+
+    # Moves a project item to "Completed" if the linked issue has +auto_complete+ enabled, and sets the linked issue's
+    # "Issue Status" field to "Fixed". Returns +nil+ when auto-complete is off (item stays at "Release in Progress" and
+    # no field is touched). The "Issue Status" update is skipped when +config.issue_fields_enabled+ is +false+ so
+    # completion still succeeds.
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    # @param deployment_id [String, nil]
+    #
+    # @return [Hash, nil] mutation result or nil
+    #
+    def complete_deployment!(project_item, deployment_id: nil)
+      issue = project_item.issue
+      return unless issue.metadata.auto_complete?
+
+      status = resolve_status_name(PlanMyStuff::Pipeline::Status::COMPLETED)
+      result = project_item.move_to!(status)
+
+      issue.set_issue_fields!('Issue Status' => 'Fixed') if PlanMyStuff.configuration.issue_fields_enabled
+
+      instrument(PlanMyStuff::Pipeline::Status::COMPLETED, project_item, deployment_id: deployment_id)
+      result
+    end
+  end
+end