plan_my_stuff 0.6.0 → 0.8.0

data/lib/plan_my_stuff/issue_metadata.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  class IssueMetadata < BaseMetadata
+  class IssueMetadata < PlanMyStuff::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
@@ -123,7 +123,7 @@ module PlanMyStuff
         #
         def normalize_links(raw)
           Array.wrap(raw).filter_map do |entry|
-            PlanMyStuff::Link.build(entry)
+            PlanMyStuff::Link.build!(entry)
           rescue ActiveModel::ValidationError, ArgumentError
             next
           end
@@ -209,16 +209,16 @@ module PlanMyStuff
     def visible_to?(user)
       return true if public?
 
-      resolved = UserResolver.resolve(user)
-      return true if UserResolver.support?(resolved)
+      resolved = PlanMyStuff::UserResolver.resolve(user)
+      return true if PlanMyStuff::UserResolver.support?(resolved)
 
-      visibility_allowlist.include?(UserResolver.user_id(resolved))
+      visibility_allowlist.include?(PlanMyStuff::UserResolver.user_id(resolved))
     end
 
     # @return [Hash]
     def to_h
       super.merge(
-        responded_at: format_time(responded_at),
+        responded_at: PlanMyStuff.format_time(responded_at),
         issues_url: issues_url,
         priority_list: priority_list,
         priority_list_priority: priority_list_priority,
@@ -227,12 +227,12 @@ module PlanMyStuff
         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),
+        waiting_on_user_at: PlanMyStuff.format_time(waiting_on_user_at),
+        waiting_on_approval_at: PlanMyStuff.format_time(waiting_on_approval_at),
+        next_reminder_at: PlanMyStuff.format_time(next_reminder_at),
         reminder_days: reminder_days,
         closed_by_inactivity: closed_by_inactivity,
-        archived_at: format_time(archived_at),
+        archived_at: PlanMyStuff.format_time(archived_at),
       )
     end
   end

data/lib/plan_my_stuff/label.rb

@@ -1,8 +1,8 @@
 # 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.
+  # 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, nil]
     attribute :name, :string
@@ -18,14 +18,14 @@ module PlanMyStuff
       #
       # @return [Array<PlanMyStuff::Label>]
       #
-      def add(issue:, labels:, user: nil)
+      def add!(issue:, labels:, user: nil)
         label_names = Array.wrap(labels)
 
         result = PlanMyStuff.client.rest(
           :add_labels_to_an_issue, issue.repo, issue.number, label_names,
         )
 
-        PMS::Cache.delete_issue(issue.repo, issue.number)
+        PlanMyStuff::Cache.delete_issue(issue.repo, issue.number)
 
         PlanMyStuff::Notifications.instrument(
           'label.added', issue, user: user, labels: label_names,
@@ -34,9 +34,8 @@ module PlanMyStuff
         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.
+      # 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
@@ -51,7 +50,25 @@ module PlanMyStuff
       rescue PlanMyStuff::APIError => e
         raise unless e.status == 404
 
-        create_label(client, repo, name, color, description)
+        create_label!(client, repo, name, color, description)
+      end
+
+      # Returns whether a label exists in the repo.
+      #
+      # @raise [PlanMyStuff::APIError] if the GET fails with any status other than 404
+      #
+      # @param repo [String, Symbol, PlanMyStuff::Repo] repo name or key
+      # @param name [String] label name
+      #
+      # @return [Boolean]
+      #
+      def exists?(repo:, name:)
+        PlanMyStuff.client.rest(:label, repo, name)
+        true
+      rescue PlanMyStuff::APIError => e
+        raise unless e.status == 404
+
+        false
       end
 
       # Removes labels from a GitHub issue.
@@ -62,7 +79,7 @@ module PlanMyStuff
       #
       # @return [Array<Array<PlanMyStuff::Label>>] results of each removal
       #
-      def remove(issue:, labels:, user: nil)
+      def remove!(issue:, labels:, user: nil)
         label_names = Array.wrap(labels)
 
         results = label_names.map do |label|
@@ -70,7 +87,7 @@ module PlanMyStuff
           result.map { |gh_label| build(gh_label, issue: issue) }
         end
 
-        PMS::Cache.delete_issue(issue.repo, issue.number)
+        PlanMyStuff::Cache.delete_issue(issue.repo, issue.number)
 
         PlanMyStuff::Notifications.instrument(
           'label.removed', issue, user: user, labels: label_names,
@@ -81,9 +98,8 @@ module PlanMyStuff
 
       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.
+        # 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]
@@ -93,7 +109,7 @@ module PlanMyStuff
         #
         # @return [void]
         #
-        def create_label(client, repo, name, color, description)
+        def create_label!(client, repo, name, color, description)
           options = {}
           options[:description] = description if description
 
@@ -117,8 +133,8 @@ module PlanMyStuff
         end
     end
 
-    # Serializes the label to a JSON-safe hash, excluding the back-reference
-    # to the parent issue to prevent recursive serialization cycles.
+    # Serializes the label to a JSON-safe hash, excluding the back-reference to the parent issue to prevent
+    # recursive serialization cycles.
     #
     # @return [Hash]
     #

data/lib/plan_my_stuff/link.rb

@@ -3,14 +3,12 @@
 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"+.
+  # 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.
+  # 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
@@ -32,11 +30,10 @@ module PlanMyStuff
     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.
+      # 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]
@@ -44,14 +41,14 @@ module PlanMyStuff
       #
       # @return [PlanMyStuff::Link]
       #
-      def build(input, type: nil, source_repo: nil)
+      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)
+            build_from_issue_like!(input, type: type)
           end
 
         link.validate!
@@ -60,8 +57,11 @@ module PlanMyStuff
 
       private
 
+        # @raise [ArgumentError] if input does not respond to #number and #repo
+        #
         # @return [PlanMyStuff::Link]
-        def build_from_issue_like(input, type:)
+        #
+        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

data/lib/plan_my_stuff/markdown.rb

@@ -5,8 +5,10 @@ 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.
+      # Renders markdown text to HTML using the configured renderer. Per-call options are deep-merged on top of
+      # config.markdown_options.
+      #
+      # @raise [ArgumentError] if the configured renderer is not an option
       #
       # @param text [String] raw markdown text
       # @param options [Hash] renderer-specific options (merged over config defaults)
@@ -22,9 +24,9 @@ module PlanMyStuff
 
         case config.markdown_renderer
         when :commonmarker
-          render_commonmarker(text, merged)
+          render_commonmarker!(text, merged)
         when :redcarpet
-          render_redcarpet(text, merged)
+          render_redcarpet!(text, merged)
         when nil
           "<code>#{ERB::Util.html_escape(text)}</code>"
         else
@@ -37,12 +39,14 @@ module PlanMyStuff
 
       private
 
+        # @raise [PlanMyStuff::Error] if commonmarker gem is not available
+        #
         # @param text [String]
         # @param options [Hash]
         #
         # @return [String]
         #
-        def render_commonmarker(text, options)
+        def render_commonmarker!(text, options)
           require('commonmarker') unless defined?(Commonmarker)
 
           if options.empty?
@@ -58,12 +62,14 @@ module PlanMyStuff
           )
         end
 
+        # @raise [PlanMyStuff::Error] if redcarpet gem is not available
+        #
         # @param text [String]
         # @param options [Hash]
         #
         # @return [String]
         #
-        def render_redcarpet(text, options)
+        def render_redcarpet!(text, options)
           require('redcarpet') unless defined?(Redcarpet)
 
           options = options.dup

data/lib/plan_my_stuff/metadata_parser.rb

@@ -30,12 +30,14 @@ module PlanMyStuff
 
     # Serializes a metadata hash and body into the stored format
     #
+    # @raise [ArgumentError] if metadata is not a Hash or PlanMyStuff::CustomFields
+    #
     # @param metadata [Hash, PlanMyStuff::CustomFields]
     # @param body [String]
     #
     # @return [String]
     #
-    def serialize(metadata, body)
+    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

data/lib/plan_my_stuff/notifications.rb

@@ -113,7 +113,7 @@ module PlanMyStuff
       logger = rails_logger
       return if logger.nil?
 
-      logger.debug { "[PMS] #{EVENT_PREFIX}.#{event} #{log_fields(payload)}" }
+      logger.debug { "[PlanMyStuff] #{EVENT_PREFIX}.#{event} #{log_fields(payload)}" }
     end
 
     # @return [Logger, nil]

data/lib/plan_my_stuff/pipeline/completed_sweep.rb

@@ -20,11 +20,11 @@ module PlanMyStuff
       #
       # @return [Array<PlanMyStuff::ProjectItem>] removed items
       #
-      def perform(project_number: nil, now: Time.current)
+      def perform!(project_number: nil, now: Time.current)
         config = PlanMyStuff.configuration
         return [] unless config.pipeline_completion_purge_enabled
 
-        number = PlanMyStuff::Pipeline.resolve_pipeline_project_number(project_number)
+        number = PlanMyStuff::Pipeline.resolve_pipeline_project_number!(project_number)
         project = PlanMyStuff::Project.find(number)
 
         completed_status = PlanMyStuff::Pipeline.resolve_status_name(

data/lib/plan_my_stuff/pipeline/issue_linker.rb

@@ -52,7 +52,7 @@ module PlanMyStuff
       # @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)
+        number = PlanMyStuff::Pipeline.resolve_pipeline_project_number!(project_number)
         project = PlanMyStuff::Project.find(number)
 
         project.items.find { |item| item.number == issue_number }

data/lib/plan_my_stuff/pipeline.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'active_support/notifications'
 require_relative 'pipeline/completed_sweep'
 require_relative 'pipeline/issue_linker'
 require_relative 'pipeline/status'
@@ -9,27 +8,23 @@ require_relative 'pipeline/testing'
 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.
+  # 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.
+    # 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.
+    # 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]
     #
@@ -48,8 +43,8 @@ module PlanMyStuff
       ))
     end
 
-    # Resolves a canonical status name to its configured display alias,
-    # falling back to the canonical name when no alias is configured.
+    # 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
     #
@@ -59,36 +54,44 @@ module PlanMyStuff
       PlanMyStuff.configuration.pipeline_statuses.fetch(canonical, canonical)
     end
 
-    # Fires an +ActiveSupport::Notifications+ event for a pipeline transition.
+    # Fires a +plan_my_stuff.pipeline.<event>+ notification.
     #
-    # @param status [String] canonical status name (used for event key)
-    # @param project_item [PlanMyStuff::ProjectItem]
+    # 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"+).
+    #
+    # @param event [String] status name or literal event suffix
+    # @param project_item [PlanMyStuff::BaseProjectItem]
     # @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)
+    def instrument(event, project_item, **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
 
-      ActiveSupport::Notifications.instrument("plan_my_stuff.pipeline.#{key}", payload)
+      PlanMyStuff::Notifications.instrument(
+        "pipeline.#{event_to_use}",
+        project_item,
+        issue_number: project_item.number,
+        **extra_to_use,
+      )
     end
 
-    # Returns the pipeline project number from the explicit argument,
-    # +pipeline_project_number+, or +default_project_number+.
+    # 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]
     #
-    # @raise [ArgumentError] if no project number can be resolved
-    #
-    def resolve_pipeline_project_number(project_number = nil)
+    def resolve_pipeline_project_number!(project_number = nil)
       config = PlanMyStuff.configuration
       result = project_number || config.pipeline_project_number || config.default_project_number
 
@@ -97,14 +100,12 @@ module PlanMyStuff
       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.
+    # 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 "Started", accounting for
-    # configured status aliases). +nil+ status is treated as not-late.
+    # 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 "Started", accounting for configured status aliases).
+    # +nil+ status is treated as not-late.
     #
     # @param project_item [PlanMyStuff::ProjectItem]
     #
@@ -114,24 +115,14 @@ module PlanMyStuff
       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
+      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.
+    # 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]
     #
@@ -144,13 +135,11 @@ module PlanMyStuff
       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.
+    # 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".
+    # 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]
     #
@@ -196,9 +185,8 @@ module PlanMyStuff
       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+.
+    # 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]
     #
@@ -210,14 +198,7 @@ module PlanMyStuff
       value = PlanMyStuff.configuration.pipeline_testing_values.fetch(:active)
       result = project_item.update_single_select_field!(field_name, value)
 
-      ActiveSupport::Notifications.instrument(
-        'plan_my_stuff.pipeline.testing',
-        project_item: project_item,
-        issue_number: project_item.number,
-        field_name: field_name,
-        value: value,
-        timestamp: Time.current,
-      )
+      instrument('testing', project_item, field_name: field_name, value: value)
 
       result
     end
@@ -237,14 +218,12 @@ module PlanMyStuff
       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.
+    # 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
+    # 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]
@@ -253,7 +232,7 @@ module PlanMyStuff
     # @return [Array<PlanMyStuff::ProjectItem>]
     #
     def start_deployment!(project_number: nil, commit_sha: nil)
-      number = resolve_pipeline_project_number(project_number)
+      number = resolve_pipeline_project_number!(project_number)
       project = PlanMyStuff::Project.find(number)
 
       ready_status = resolve_status_name(PlanMyStuff::Pipeline::Status::READY_FOR_RELEASE)
@@ -275,9 +254,8 @@ module PlanMyStuff
       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").
+    # 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]

data/lib/plan_my_stuff/project.rb

@@ -44,7 +44,7 @@ module PlanMyStuff
         project_id = new_project[:id]
         project_number = new_project[:number]
 
-        serialized_readme = PlanMyStuff::MetadataParser.serialize(project_metadata.to_h, readme)
+        serialized_readme = PlanMyStuff::MetadataParser.serialize!(project_metadata.to_h, readme)
         update_input = { projectId: project_id, readme: serialized_readme }
         update_input[:shortDescription] = description if description.present?
 
@@ -60,12 +60,12 @@ module PlanMyStuff
       # project - call +TestingProject.find+ for those, or +BaseProject.find+
       # if you want either type.
       #
+      # @raise [ArgumentError] if the project is a testing project
+      #
       # @param number [Integer]
       # @param paginate [Symbol] :auto (default) or :cursor
       # @param cursor [String, nil] pagination cursor for :cursor mode
       #
-      # @raise [ArgumentError] if the project is a testing project
-      #
       # @return [PlanMyStuff::Project]
       #
       def find(number, paginate: :auto, cursor: nil)
@@ -91,7 +91,7 @@ module PlanMyStuff
 
     private
 
-      # Returns the item class used to build items for testing projects.
+      # Returns the item class used to build items for regular projects.
       #
       # @return [Class]
       #

data/lib/plan_my_stuff/project_item_metadata.rb

@@ -10,7 +10,7 @@ module PlanMyStuff
   # (T-049), which will assign non-GitHub users (e.g. internal QA
   # accounts) to draft items via the +pms_assignee+ field.
   #
-  class ProjectItemMetadata < BaseMetadata
+  class ProjectItemMetadata < PlanMyStuff::BaseMetadata
     # @return [Integer, nil] consuming app user id of the PMS-side assignee
     attr_accessor :pms_assignee
 

data/lib/plan_my_stuff/project_metadata.rb

@@ -2,7 +2,7 @@
 
 module PlanMyStuff
   # Metadata for regular (non-testing) projects.
-  class ProjectMetadata < BaseProjectMetadata
+  class ProjectMetadata < PlanMyStuff::BaseProjectMetadata
     class << self
       # Builds a ProjectMetadata from a parsed hash (e.g. from MetadataParser)
       #

data/lib/plan_my_stuff/reminders/closer.rb

@@ -63,7 +63,7 @@ module PlanMyStuff
           return if @issue.labels.include?(label)
 
           PlanMyStuff::Label.ensure!(repo: @issue.repo, name: label)
-          PlanMyStuff::Label.add(issue: @issue, labels: [label])
+          PlanMyStuff::Label.add!(issue: @issue, labels: [label])
         end
     end
   end