plan_my_stuff 0.2.0 → 0.4.0

data/lib/plan_my_stuff/pipeline.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+require_relative 'pipeline/issue_linker'
+require_relative 'pipeline/status'
+
+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 (+submit!+, +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.
+    #
+    # @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 an +ActiveSupport::Notifications+ event for a pipeline transition.
+    #
+    # @param status [String] canonical status name (used for event key)
+    # @param project_item [PlanMyStuff::ProjectItem]
+    # @param extra [Hash] additional payload entries
+    #
+    # @return [void]
+    #
+    def instrument(status, project_item, **extra)
+      key = PlanMyStuff::Pipeline::Status.key_for(status)
+      payload = {
+        project_item: project_item,
+        issue_number: project_item.number,
+        status: status,
+        timestamp: Time.current,
+      }.merge(extra)
+
+      ActiveSupport::Notifications.instrument("plan_my_stuff.pipeline.#{key}", payload)
+    end
+
+    # Returns the pipeline project number from the explicit argument,
+    # +pipeline_project_number+, or +default_project_number+.
+    #
+    # @param project_number [Integer, nil]
+    #
+    # @return [Integer]
+    #
+    # @raise [ArgumentError] if no project number can be resolved
+    #
+    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
+
+    # Adds an issue to the pipeline project, moves it to "Submitted",
+    # and assigns the given developer.
+    #
+    # Called when an issue is assigned to a dev, NOT on issue creation.
+    # Un-triaged issues should not be in the pipeline.
+    #
+    # @param issue [PlanMyStuff::Issue]
+    # @param assignee [String] GitHub username
+    # @param project_number [Integer, nil]
+    #
+    # @return [PlanMyStuff::ProjectItem]
+    #
+    def submit!(issue, assignee:, project_number: nil)
+      guard_approvals!(issue)
+      number = resolve_pipeline_project_number(project_number)
+      project_item = PlanMyStuff::ProjectItem.create!(issue, project_number: number)
+
+      status = resolve_status_name(PlanMyStuff::Pipeline::Status::SUBMITTED)
+      project_item.move_to!(status)
+      project_item.assign!(assignee)
+
+      instrument(PlanMyStuff::Pipeline::Status::SUBMITTED, project_item)
+      project_item
+    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 +plan_my_stuff.pipeline.removed+. Additionally fires
+    # +plan_my_stuff.pipeline.removed_late+ when +prior_status+ is past
+    # "Started" (i.e. anything other than "Submitted" or "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!
+
+      payload = {
+        project_item: project_item,
+        issue_number: project_item.number,
+        prior_status: prior_status,
+        timestamp: Time.current,
+      }
+
+      ActiveSupport::Notifications.instrument('plan_my_stuff.pipeline.removed', payload)
+
+      if late_removal?(prior_status)
+        ActiveSupport::Notifications.instrument('plan_my_stuff.pipeline.removed_late', payload)
+      end
+
+      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?
+
+      early_statuses = [
+        resolve_status_name(PlanMyStuff::Pipeline::Status::SUBMITTED),
+        resolve_status_name(PlanMyStuff::Pipeline::Status::STARTED),
+      ]
+
+      early_statuses.exclude?(prior_status)
+    end
+
+    # Moves a project item to "Started".
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    #
+    # @return [Hash] mutation result
+    #
+    def take!(project_item)
+      guard_approvals!(project_item&.issue)
+      status = resolve_status_name(PlanMyStuff::Pipeline::Status::STARTED)
+      result = project_item.move_to!(status)
+
+      instrument(PlanMyStuff::Pipeline::Status::STARTED, project_item)
+      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
+
+    # Moves a project item to "Testing".
+    #
+    # @param project_item [PlanMyStuff::ProjectItem]
+    #
+    # @return [Hash] mutation result
+    #
+    def request_testing!(project_item)
+      guard_approvals!(project_item&.issue)
+      status = resolve_status_name(PlanMyStuff::Pipeline::Status::TESTING)
+      result = project_item.move_to!(status)
+
+      instrument(PlanMyStuff::Pipeline::Status::TESTING, project_item)
+      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. Returns +nil+ when auto-complete is off
+    # (item stays at "Release in Progress").
+    #
+    # @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)
+
+      instrument(PlanMyStuff::Pipeline::Status::COMPLETED, project_item, deployment_id: deployment_id)
+      result
+    end
+  end
+end