plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/label.rb

@@ -1,46 +1,123 @@
 # 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] 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,
+        )
+
+        PlanMyStuff::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(e) unless e.status == 404
+
+        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:, do_raise: true)
+        PlanMyStuff.client.rest(:label, repo, name)
+        true
+      rescue PlanMyStuff::APIError => e
+        raise(e) if do_raise && e.status != 404
+
+        false
+      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
+
+        PlanMyStuff::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(e) unless e.status == 422
+        end
+
         # Hydrates a Label from a GitHub API response.
         #
         # @param github_label [Object] Octokit label response
@@ -49,11 +126,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
+
+        # @raise [ArgumentError] if input does not respond to #number and #repo
+        #
+        # @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/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,11 +24,11 @@ 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>#{text}</code>"
+          "<code>#{ERB::Util.html_escape(text)}</code>"
         else
           raise(
             ArgumentError,
@@ -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

@@ -4,7 +4,22 @@ require 'json'
 
 module PlanMyStuff
   module MetadataParser
-    METADATA_PATTERN = /\A<!-- pms-metadata:(.*?) -->\n*/m
+    # Collapsible <details> block containing a JSON code fence. Renders visibly on
+    # GitHub (issue #58) instead of being hidden in an HTML comment.
+    METADATA_PATTERN = %r{
+      \A<details><summary>pms-metadata</summary>\n\n
+      ```json\n(.*?)\n```\n\n
+      </details>\n*
+    }mx
+
+    # Visible attachments block emitted after the metadata block when the
+    # metadata carries non-empty +attachments+ (issue #70). Parse strips it
+    # so round-trips stay clean.
+    ATTACHMENTS_PATTERN = %r{
+      \A<details><summary>attachments\ \(\d+\)</summary>\n\n
+      .*?\n\n
+      </details>\n*
+    }mx
 
     module_function
 
@@ -16,12 +31,11 @@ module PlanMyStuff
     #
     def parse(raw_body)
       return { metadata: {}, body: '' } if raw_body.blank?
+      return { metadata: {}, body: raw_body } unless raw_body.match?(METADATA_PATTERN)
 
       match = raw_body.match(METADATA_PATTERN)
-      return { metadata: {}, body: raw_body } if match.nil?
-
       metadata = JSON.parse(match[1], symbolize_names: true)
-      body = raw_body.sub(METADATA_PATTERN, '')
+      body = raw_body.sub(METADATA_PATTERN, '').sub(ATTACHMENTS_PATTERN, '')
 
       { metadata: metadata, body: body }
     rescue JSON::ParserError
@@ -30,24 +44,49 @@ 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
 
-      json =
-        if metadata.is_a?(PlanMyStuff::CustomFields)
-          metadata.to_json
-        else
-          JSON.pretty_generate(metadata)
-        end
+      hash = metadata.is_a?(PlanMyStuff::CustomFields) ? metadata.to_h : metadata
+      json = JSON.pretty_generate(hash)
+
+      "<details><summary>pms-metadata</summary>\n\n```json\n#{json}\n```\n\n</details>\n\n" \
+        "#{attachments_block(hash)}#{body}"
+    end
 
-      "<!-- pms-metadata:#{json} -->\n\n#{body}"
+    # Renders the visible attachments block when +metadata+ carries
+    # non-empty +:attachments+, otherwise returns an empty string.
+    #
+    # @param metadata [Hash]
+    #
+    # @return [String]
+    #
+    def attachments_block(metadata)
+      attachments = metadata[:attachments]
+      return '' if attachments.blank?
+
+      lines = attachments.map { |a| attachment_line(a) }.join("\n")
+      "<details><summary>attachments (#{attachments.size})</summary>\n\n#{lines}\n\n</details>\n\n"
+    end
+
+    # @param attachment [Hash{Symbol=>String}]
+    #
+    # @return [String]
+    #
+    def attachment_line(attachment)
+      url = "https://github.com/#{attachment[:owner]}/#{attachment[:repo]}" \
+        "/blob/#{attachment[:sha]}/#{attachment[:path]}"
+      safe_filename = attachment[:filename].to_s.gsub(']', '\]')
+      "- [#{safe_filename}](#{url})"
     end
   end
 end

data/lib/plan_my_stuff/notifications.rb

@@ -0,0 +1,148 @@
+# 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 +<event>.plan_my_stuff+ namespace via
+  # +ActiveSupport::Notifications+ (Rails convention: event first,
+  # library last - matches +sql.active_record+, +deliver.action_mailer+).
+  # Subscribers run synchronously.
+  #
+  module Notifications
+    module_function
+
+    EVENT_SUFFIX = 'plan_my_stuff'
+    SKIPPED_LOG_KEYS = %i[user timestamp visibility visibility_allowlist].freeze
+
+    # Fires +<event>.plan_my_stuff+ with a normalized payload.
+    #
+    # @param event [String] e.g. +'issue_created'+
+    # @param resource [Object] domain object (+Issue+, +Comment+, +ProjectItem+, ...), or an +Array+ of resources for a
+    #   batch event (keyed by the pluralized element key, e.g. +:project_items+)
+    # @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}.#{EVENT_SUFFIX}", 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. An +Array+ recurses on its first element and pluralizes that key, so
+    # batch events carry the full set under one key (a batch of project items keys as +:project_items+, a batch of
+    # issues as +:issues+, an empty/unknown batch as +:resources+).
+    #
+    # @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
+      when Array then :"#{infer_resource_key(resource.first)}s"
+      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 { "[PlanMyStuff] #{event}.#{EVENT_SUFFIX} #{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/completed_sweep.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Pipeline
+    # Removes pipeline project items that have been at +Completed+ for
+    # longer than the configured TTL.
+    #
+    # Driven by +RemindersSweepJob+ so the gem ships one scheduled
+    # entrypoint. Items are removed via +Pipeline.remove!+ so subscribers
+    # see the standard +pipeline_removed.plan_my_stuff+ event.
+    #
+    module CompletedSweep
+      module_function
+
+      # Runs the sweep. No-op when
+      # +configuration.pipeline_completion_purge_enabled+ is false.
+      #
+      # @param project_number [Integer, nil]
+      # @param now [Time]
+      #
+      # @return [Array<PlanMyStuff::ProjectItem>] removed items
+      #
+      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)
+        project = PlanMyStuff::Project.find(number)
+
+        completed_status = PlanMyStuff::Pipeline.resolve_status_name(
+          PlanMyStuff::Pipeline::Status::COMPLETED,
+        )
+        ttl = config.pipeline_completion_ttl_hours.hours
+
+        candidates = project.items.select do |item|
+          item.status == completed_status &&
+            item.updated_at.present? &&
+            item.updated_at + ttl < now
+        end
+
+        candidates.each { |item| PlanMyStuff::Pipeline.remove!(item) }
+        candidates
+      end
+    end
+  end
+end