ace-review 0.49.0

data/lib/ace/review/atoms/pr_comment_formatter.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require "time"
+require "yaml"
+
+module Ace
+  module Review
+    module Atoms
+      # Format PR comments into a structured markdown report
+      # Pure transformation - no side effects
+      class PrCommentFormatter
+        # Review state to human-readable status
+        REVIEW_STATES = {
+          "APPROVED" => "Approved",
+          "CHANGES_REQUESTED" => "Changes Requested",
+          "COMMENTED" => "Commented",
+          "DISMISSED" => "Dismissed",
+          "PENDING" => "Pending"
+        }.freeze
+
+        # Format comments data into markdown report
+        #
+        # @param comments_data [Hash] Data from GhPrCommentFetcher
+        # @return [String] Formatted markdown report
+        def self.format(comments_data)
+          return nil unless comments_data && comments_data[:success]
+
+          pr_number = comments_data[:pr_number]
+          pr_title = comments_data[:pr_title]
+          comments = comments_data[:comments] || []
+          reviews = comments_data[:reviews] || []
+          review_threads = comments_data[:review_threads] || []
+
+          # Build report sections
+          frontmatter = build_frontmatter(comments_data)
+          summary = build_summary(comments, reviews, review_threads, pr_number, pr_title)
+          inline_section = build_inline_comments_section(review_threads)
+          unresolved_section = build_unresolved_section(comments, reviews)
+          resolved_section = build_resolved_section(reviews)
+          comments_table = build_comments_table(comments, reviews)
+
+          # Combine sections
+          sections = [frontmatter, summary]
+          sections << inline_section unless inline_section.nil?
+          sections << unresolved_section unless unresolved_section.nil?
+          sections << resolved_section unless resolved_section.nil?
+          sections << comments_table unless comments_table.nil?
+
+          sections.join("\n")
+        end
+
+        # Build YAML frontmatter
+        #
+        # @param comments_data [Hash] Comments data
+        # @return [String] YAML frontmatter block
+        def self.build_frontmatter(comments_data)
+          metadata = {
+            "source" => "pr-comments",
+            "pr_number" => comments_data[:pr_number],
+            "fetched_at" => Time.now.utc.iso8601
+          }
+
+          "---\n#{YAML.dump(metadata).sub(/^---\n/, "")}---\n"
+        end
+
+        # Build summary section
+        #
+        # @param comments [Array<Hash>] Issue comments
+        # @param reviews [Array<Hash>] Code reviews
+        # @param review_threads [Array<Hash>] Inline review threads
+        # @param pr_number [Integer] PR number
+        # @param pr_title [String] PR title
+        # @return [String] Summary markdown
+        def self.build_summary(comments, reviews, review_threads, pr_number, pr_title)
+          total_comments = comments.size + reviews.size
+          inline_thread_count = review_threads.size
+          reviewers = extract_reviewers(comments, reviews, review_threads)
+          unresolved_count = count_unresolved(comments, reviews, review_threads)
+
+          summary = "# Developer Feedback from PR ##{pr_number}\n\n"
+          summary += "> #{pr_title}\n\n" if pr_title && !pr_title.empty?
+          summary += "## Summary\n\n"
+          summary += "- Total comments: #{total_comments}\n"
+          summary += "- Inline code comments: #{inline_thread_count}\n" if inline_thread_count > 0
+          summary += "- Unresolved items: #{unresolved_count}\n"
+          summary += "- Reviewers: #{reviewers.map { |r| "@#{r}" }.join(", ")}\n" if reviewers.any?
+          summary
+        end
+
+        # Build unresolved feedback section
+        #
+        # @param comments [Array<Hash>] Issue comments
+        # @param reviews [Array<Hash>] Code reviews
+        # @return [String, nil] Unresolved section or nil if empty
+        def self.build_unresolved_section(comments, reviews)
+          unresolved = []
+
+          # Add comments (all issue comments are considered unresolved/open)
+          comments.each do |comment|
+            unresolved << {
+              author: comment[:author],
+              body: comment[:body],
+              id: comment[:id],
+              type: "comment",
+              created_at: comment[:created_at]
+            }
+          end
+
+          # Add reviews with "CHANGES_REQUESTED" state
+          reviews.select { |r| r[:state] == "CHANGES_REQUESTED" }.each do |review|
+            unresolved << {
+              author: review[:author],
+              body: review[:body],
+              id: review[:id],
+              type: "changes_requested",
+              created_at: review[:created_at]
+            }
+          end
+
+          return nil if unresolved.empty?
+
+          section = "\n## Unresolved Feedback\n\n"
+
+          unresolved.each do |item|
+            section += "### @#{item[:author]} (#{item[:type]}: #{item[:id]})\n\n"
+            section += format_body(item[:body])
+            section += "\n\n"
+          end
+
+          section
+        end
+
+        # Build inline code comments section
+        #
+        # @param review_threads [Array<Hash>] Review threads from GraphQL
+        # @return [String, nil] Inline comments section or nil if empty
+        def self.build_inline_comments_section(review_threads)
+          return nil if review_threads.nil? || review_threads.empty?
+
+          section = "\n## Inline Code Comments\n\n"
+
+          review_threads.each do |thread|
+            path = thread[:path] || "unknown"
+            line = thread[:line]
+            thread_id = thread[:id]
+            is_resolved = thread[:is_resolved]
+            status = is_resolved ? "Resolved" : "Unresolved"
+
+            # Header with file:line, thread ID, and status
+            location = line ? "#{path}:#{line}" : path
+            section += "### #{location} (thread: #{thread_id}) - #{status}\n\n"
+
+            # Format each comment in the thread
+            (thread[:comments] || []).each do |comment|
+              author = comment[:author] || "unknown"
+              body = comment[:body]&.strip
+              next if body.nil? || body.empty?
+
+              # Quote the comment with author prefix
+              section += "> @#{author}: #{body.gsub("\n", "\n> ")}\n\n"
+            end
+          end
+
+          section
+        end
+
+        # Build resolved feedback section
+        #
+        # @param reviews [Array<Hash>] Code reviews
+        # @return [String, nil] Resolved section or nil if empty
+        def self.build_resolved_section(reviews)
+          resolved = []
+
+          # Add approvals
+          reviews.select { |r| r[:state] == "APPROVED" }.each do |review|
+            resolved << "@#{review[:author]} approved changes"
+          end
+
+          return nil if resolved.empty?
+
+          section = "\n## Resolved Feedback\n\n"
+          resolved.each do |item|
+            section += "- #{item}\n"
+          end
+
+          section
+        end
+
+        # Build comments table for quick reference
+        #
+        # @param comments [Array<Hash>] Issue comments
+        # @param reviews [Array<Hash>] Code reviews
+        # @return [String, nil] Table markdown or nil if empty
+        def self.build_comments_table(comments, reviews)
+          all_items = []
+
+          comments.each do |c|
+            all_items << {
+              author: c[:author],
+              type: "Comment",
+              status: "Open",
+              preview: truncate_body(c[:body], 50),
+              id: c[:id]
+            }
+          end
+
+          reviews.each do |r|
+            status = REVIEW_STATES[r[:state]] || r[:state]
+            all_items << {
+              author: r[:author],
+              type: "Review",
+              status: status,
+              preview: truncate_body(r[:body], 50),
+              id: r[:id]
+            }
+          end
+
+          return nil if all_items.empty?
+
+          table = "\n## All Comments\n\n"
+          table += "| Author | Type | Status | Comment | ID |\n"
+          table += "|--------|------|--------|---------|----|\n"
+
+          all_items.each do |item|
+            # Wrap ID in backticks for readability
+            table += "| @#{item[:author]} | #{item[:type]} | #{item[:status]} | #{item[:preview]} | `#{item[:id]}` |\n"
+          end
+
+          table
+        end
+
+        # Extract unique reviewers from comments, reviews, and threads
+        #
+        # @param comments [Array<Hash>] Issue comments
+        # @param reviews [Array<Hash>] Code reviews
+        # @param review_threads [Array<Hash>] Inline review threads
+        # @return [Array<String>] Unique reviewer usernames
+        def self.extract_reviewers(comments, reviews, review_threads = [])
+          authors = []
+          authors.concat(comments.map { |c| c[:author] })
+          authors.concat(reviews.map { |r| r[:author] })
+          # Extract authors from review thread comments
+          review_threads.each do |thread|
+            (thread[:comments] || []).each do |comment|
+              authors << comment[:author]
+            end
+          end
+          authors.uniq.compact.sort
+        end
+
+        # Count unresolved items
+        # Counts actionable items (not informational/FYI comments)
+        #
+        # @param comments [Array<Hash>] Issue comments
+        # @param reviews [Array<Hash>] Code reviews
+        # @param review_threads [Array<Hash>] Inline review threads
+        # @return [Integer] Count of unresolved items
+        def self.count_unresolved(comments, reviews, review_threads = [])
+          unresolved_threads = review_threads.count { |t| !t[:is_resolved] }
+          actionable_comments = comments.count { |c| actionable_comment?(c[:body]) }
+          actionable_comments + reviews.count { |r| r[:state] == "CHANGES_REQUESTED" } + unresolved_threads
+        end
+
+        # Check if a comment appears to be actionable (vs informational/FYI)
+        # Heuristic: contains question marks, action words, or change requests
+        #
+        # @param body [String] Comment body
+        # @return [Boolean] true if comment seems actionable
+        def self.actionable_comment?(body)
+          return true if body.nil? || body.empty?  # Default to actionable if can't determine
+
+          lowered = body.downcase
+          # Action indicators
+          lowered.include?("?") ||                      # Questions
+            lowered.include?("please") ||               # Polite requests
+            lowered.include?("should") ||               # Suggestions
+            lowered.include?("could you") ||            # Requests
+            lowered.include?("need to") ||              # Requirements
+            lowered.include?("must") ||                 # Requirements
+            lowered.include?("fix") ||                  # Fix requests
+            lowered.include?("change") ||               # Change requests
+            lowered.include?("update") ||               # Update requests
+            lowered.include?("consider") ||             # Suggestions
+            lowered.match?(/\btodo\b/i)                 # TODOs
+        end
+
+        # Format comment body with proper indentation/quoting
+        #
+        # @param body [String] Comment body
+        # @return [String] Formatted body
+        def self.format_body(body)
+          return "" if body.nil? || body.empty?
+
+          # Quote each line
+          body.lines.map { |line| "> #{line.rstrip}" }.join("\n")
+        end
+
+        # Truncate body for table preview
+        #
+        # @param body [String] Comment body
+        # @param max_length [Integer] Maximum length
+        # @return [String] Truncated body (pipe-safe for markdown tables)
+        def self.truncate_body(body, max_length)
+          return "" if body.nil?
+
+          # Replace newlines with visual indicator, collapse other whitespace
+          cleaned = body.gsub(/[\r\n]+/, " \u21b5 ").gsub(/[ \t]+/, " ").strip
+
+          # Escape pipe characters to prevent breaking markdown tables
+          cleaned = cleaned.gsub("|", "\\|")
+
+          if cleaned.length > max_length
+            "#{cleaned[0...max_length]}..."
+          else
+            cleaned
+          end
+        end
+
+        private_class_method :build_frontmatter, :build_summary, :build_inline_comments_section,
+          :build_unresolved_section, :build_resolved_section, :build_comments_table,
+          :extract_reviewers, :count_unresolved, :actionable_comment?, :format_body, :truncate_body
+      end
+    end
+  end
+end

data/lib/ace/review/atoms/preset_validator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Ace
+  module Review
+    module Atoms
+      # Validates preset references and detects circular dependencies
+      class PresetValidator
+        # Maximum recursion depth for preset composition
+        # A sane limit to prevent stack overflows from deep, non-circular nesting
+        MAX_DEPTH = 10
+
+        # Validate preset name format
+        # Returns { success: true } if valid
+        # Returns { success: false, error: "..." } if invalid
+        def self.validate_preset_name(preset_name)
+          return {success: false, error: "Preset name cannot be nil or empty"} if preset_name.nil? || preset_name.empty?
+
+          # Check for path traversal attempts
+          if preset_name.start_with?("/", "\\")
+            return {
+              success: false,
+              error: "Invalid preset name '#{preset_name}': absolute paths are not allowed"
+            }
+          end
+
+          if preset_name.include?("..") || preset_name.include?("/") || preset_name.include?("\\")
+            return {
+              success: false,
+              error: "Invalid preset name '#{preset_name}': cannot contain path separators or '..' sequences"
+            }
+          end
+
+          # Check for reasonable length
+          if preset_name.length > 100
+            return {
+              success: false,
+              error: "Preset name too long (max 100 characters): '#{preset_name[0..20]}...'"
+            }
+          end
+
+          {success: true}
+        end
+
+        # Check if a preset exists in the preset manager
+        def self.preset_exists?(preset_name, preset_manager)
+          preset_manager.preset_exists?(preset_name)
+        end
+
+        # Detect circular dependencies in preset composition
+        # Returns { success: true } if no circular dependency
+        # Returns { success: false, error: "..." } if circular dependency found
+        def self.check_circular_dependency(preset_name, preset_chain)
+          if preset_chain.include?(preset_name)
+            {
+              success: false,
+              error: "Circular dependency detected: #{(preset_chain + [preset_name]).join(" -> ")}"
+            }
+          elsif preset_chain.size >= MAX_DEPTH
+            {
+              success: false,
+              error: "Maximum preset nesting depth (#{MAX_DEPTH}) exceeded: #{preset_chain.join(" -> ")}"
+            }
+          else
+            {success: true}
+          end
+        end
+
+        # Validate a list of preset names
+        # Returns { success: true, valid: [], missing: [] }
+        def self.validate_presets(preset_names, preset_manager)
+          valid = []
+          missing = []
+
+          preset_names.each do |name|
+            if preset_exists?(name, preset_manager)
+              valid << name
+            else
+              missing << name
+            end
+          end
+
+          {
+            success: missing.empty?,
+            valid: valid,
+            missing: missing
+          }
+        end
+
+        # Extract preset references from a preset's configuration
+        # Returns array of preset names referenced in the 'presets:' key at root level
+        def self.extract_preset_references(preset_data)
+          return [] unless preset_data
+
+          # Look for root-level 'presets' key (both string and symbol)
+          presets = preset_data["presets"] || preset_data[:presets] || []
+
+          # Ensure we return an array of strings
+          Array(presets).map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/ace/review/atoms/priority_filter.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Ace
+  module Review
+    module Atoms
+      # Filters feedback items by priority level with optional range support.
+      #
+      # Supports exact matching ("high") and inclusive range matching ("high+").
+      # Range matching includes the specified priority and all higher priorities.
+      #
+      # Priority hierarchy (highest to lowest): critical > high > medium > low
+      #
+      # @example Exact matching
+      #   PriorityFilter.matches?("high", "high")
+      #   #=> true
+      #
+      #   PriorityFilter.matches?("medium", "high")
+      #   #=> false
+      #
+      # @example Range matching with + suffix
+      #   PriorityFilter.matches?("high", "medium+")
+      #   #=> true (high >= medium)
+      #
+      #   PriorityFilter.matches?("critical", "medium+")
+      #   #=> true (critical >= medium)
+      #
+      #   PriorityFilter.matches?("low", "medium+")
+      #   #=> false (low < medium)
+      #
+      class PriorityFilter
+        # Priority levels in descending order (highest first)
+        PRIORITY_ORDER = {
+          "critical" => 4,
+          "high" => 3,
+          "medium" => 2,
+          "low" => 1
+        }.freeze
+
+        VALID_PRIORITIES = PRIORITY_ORDER.keys.freeze
+
+        # Parse a priority filter string into its components
+        #
+        # @param filter_string [String] Priority filter like "medium" or "medium+"
+        # @return [Hash, nil] Hash with :priority and :inclusive keys, or nil if invalid
+        #
+        # @example Exact match
+        #   PriorityFilter.parse("high")
+        #   #=> { priority: "high", inclusive: false }
+        #
+        # @example Range match
+        #   PriorityFilter.parse("medium+")
+        #   #=> { priority: "medium", inclusive: true }
+        #
+        # @example Invalid priority
+        #   PriorityFilter.parse("urgent")
+        #   #=> nil
+        def self.parse(filter_string)
+          return nil if filter_string.nil? || filter_string.empty?
+
+          # Check for + suffix (inclusive range)
+          inclusive = filter_string.end_with?("+")
+          priority = inclusive ? filter_string.chomp("+") : filter_string
+
+          # Validate priority
+          return nil unless VALID_PRIORITIES.include?(priority)
+
+          {priority: priority, inclusive: inclusive}
+        end
+
+        # Check if an item priority matches a filter string
+        #
+        # @param item_priority [String] The priority of the item ("critical", "high", etc.)
+        # @param filter_string [String] The filter string ("high" or "high+")
+        # @return [Boolean] True if the item priority matches the filter
+        #
+        # @example Exact match
+        #   PriorityFilter.matches?("high", "high")
+        #   #=> true
+        #
+        #   PriorityFilter.matches?("medium", "high")
+        #   #=> false
+        #
+        # @example Range match
+        #   PriorityFilter.matches?("critical", "high+")
+        #   #=> true
+        #
+        #   PriorityFilter.matches?("high", "high+")
+        #   #=> true
+        #
+        #   PriorityFilter.matches?("medium", "high+")
+        #   #=> false
+        def self.matches?(item_priority, filter_string)
+          return false if item_priority.nil? || filter_string.nil?
+
+          parsed = parse(filter_string)
+          return false if parsed.nil?
+
+          item_level = PRIORITY_ORDER[item_priority]
+          filter_level = PRIORITY_ORDER[parsed[:priority]]
+
+          # Unknown item priority doesn't match
+          return false if item_level.nil?
+
+          if parsed[:inclusive]
+            # Range match: item priority must be >= filter priority
+            item_level >= filter_level
+          else
+            # Exact match
+            item_priority == parsed[:priority]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/review/atoms/retry_with_backoff.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Ace
+  module Review
+    module Atoms
+      # Pure function for retrying operations with exponential backoff
+      #
+      # This atom provides a reusable retry mechanism with exponential backoff
+      # for operations that may experience transient failures (network issues,
+      # timeouts, temporary unavailability).
+      module RetryWithBackoff
+        # Retry a block with exponential backoff
+        #
+        # @param options [Hash] Retry options
+        # @option options [Integer] :max_retries Maximum retry attempts (default: 3)
+        # @option options [Integer] :initial_backoff Initial backoff in seconds (default: 1)
+        # @option options [Integer] :max_backoff Maximum backoff in seconds (default: 32)
+        # @option options [Proc] :retryable_check Custom proc to check if error is retryable.
+        #   Receives result hash, should return boolean. Defaults to network error check.
+        # @option options [Class] :error_class Exception class to raise on retry exhaustion
+        #   (default: Ace::Review::Errors::GhNetworkError)
+        # @yield Block to retry - should return a hash with :success and :stderr keys
+        # @return Result from successful execution
+        # @raise [error_class] if all retries exhausted
+        def self.execute(options = {})
+          max_retries = options[:max_retries] || 3
+          backoff = options[:initial_backoff] || 1
+          max_backoff = options[:max_backoff] || 32
+          retryable_check = options[:retryable_check] || method(:default_retryable_check)
+          error_class = options[:error_class] || Ace::Review::Errors::GhNetworkError
+          attempt = 0
+
+          loop do
+            result = yield
+
+            # Success - return result
+            return result if result[:success]
+
+            # Check if error is retryable using provided check or default
+            unless retryable_check.call(result)
+              return result
+            end
+
+            # Increment attempt
+            attempt += 1
+
+            # Exhausted retries
+            if attempt >= max_retries
+              error_msg = result[:stderr] || result[:error] || "Unknown error"
+              raise error_class, "Operation failed after #{max_retries} retries: #{error_msg}"
+            end
+
+            # Wait before retry with exponential backoff, capped at max_backoff
+            sleep(backoff)
+            backoff = [backoff * 2, max_backoff].min
+          end
+        end
+
+        # Default check for retryable errors (network/timeout errors)
+        #
+        # @param result [Hash] Result from operation (should have :stderr or :error key)
+        # @return [Boolean] true if error is retryable
+        def self.default_retryable_check(result)
+          error_msg = (result[:stderr] || result[:error]).to_s.downcase
+
+          # Network-related errors are retryable
+          error_msg.include?("timeout") ||
+            error_msg.include?("connection") ||
+            error_msg.include?("network") ||
+            error_msg.include?("temporary failure")
+        end
+      end
+    end
+  end
+end

data/lib/ace/review/atoms/slug_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ace
+  module Review
+    module Atoms
+      # Generates URL-safe slugs from text strings
+      #
+      # Handles edge cases:
+      # - Special characters replaced with hyphens
+      # - Consecutive hyphens collapsed
+      # - Leading/trailing hyphens removed
+      # - Length truncation for filesystem safety
+      class SlugGenerator
+        DEFAULT_MAX_LENGTH = 64
+
+        # Generate a URL-safe slug from text
+        #
+        # @param text [String] The text to convert to a slug
+        # @param max_length [Integer] Maximum slug length (default: 64)
+        # @return [String] URL-safe slug
+        #
+        # @example Basic usage
+        #   SlugGenerator.generate("google:gemini-2.5-flash")
+        #   #=> "google-gemini-2-5-flash"
+        #
+        # @example With special characters
+        #   SlugGenerator.generate("model::name@provider")
+        #   #=> "model-name-provider"
+        #
+        # @example With leading/trailing special chars
+        #   SlugGenerator.generate("@model-name@")
+        #   #=> "model-name"
+        #
+        # @example Long text truncation
+        #   SlugGenerator.generate("very-long-model-name...", max_length: 10)
+        #   #=> "very-long" (truncated, trailing hyphen removed)
+        def self.generate(text, max_length: DEFAULT_MAX_LENGTH)
+          return "" if text.nil? || text.empty?
+
+          text
+            .gsub(/[^a-zA-Z0-9\-_]/, "-").squeeze("-")              # Collapse consecutive hyphens
+            .gsub(/\A-|-\z/, "")          # Remove leading/trailing hyphens
+            .downcase
+            .slice(0, max_length)         # Truncate to max length
+            .gsub(/-\z/, "")              # Remove trailing hyphen after truncation
+        end
+      end
+    end
+  end
+end