ace-review 0.49.0

data/lib/ace/review/molecules/context_composer.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Review
+    module Molecules
+      # Composes context.md files with YAML frontmatter for ace-bundle integration
+      # Follows the pattern from ace-docs DocumentAnalysisPrompt
+      class ContextComposer
+        # Create context.md with YAML frontmatter for review context
+        # @param base_instructions [String] Base instructions for the context
+        # @param context_config [Hash] Context configuration (presets, files, diffs, commands)
+        # @param subject_config [Hash, nil] Optional subject configuration for scope section
+        # @return [String] Complete context.md content with YAML frontmatter
+        def self.create_context_md(base_instructions, context_config, subject_config = nil)
+          # Normalize context configuration following ace-docs pattern
+          normalized_config = normalize_context_config(context_config)
+
+          frontmatter = {"bundle" => normalized_config}
+
+          # Build review scope section if subject config provided
+          scope_section = build_review_scope_section(subject_config) if subject_config
+
+          # context.md = frontmatter + base instructions + scope section
+          # YAML.dump adds opening --- but not closing, we add closing ---
+          "#{YAML.dump(frontmatter).strip}\n---\n\n#{base_instructions}\n\n#{scope_section}".strip
+        end
+
+        # Save context.md to specified directory
+        # @param context_md [String] The context.md content
+        # @param cache_dir [String] Directory to save context.md
+        # @return [String] Path to saved context.md file
+        def self.save_context_md(context_md, cache_dir)
+          context_file_path = File.join(cache_dir, "context.md")
+          File.write(context_file_path, context_md)
+          context_file_path
+        end
+
+        # Load context.md via ace-bundle
+        # @param context_file_path [String] Path to context.md file
+        # @return [String] Content with embedded files and context
+        def self.load_context_via_ace_bundle(context_file_path)
+          require "ace/bundle"
+
+          # Use ace-bundle to load context.md - processes presets and files from frontmatter
+          result = Ace::Bundle.load_file(context_file_path)
+          result.content
+        rescue LoadError
+          raise Ace::Review::Errors::ContextComposerError, "ace-bundle not available - required for context.md pattern"
+        rescue => e
+          raise Ace::Review::Errors::ContextComposerError, "ace-bundle loading failed: #{e.message}"
+        end
+
+        private
+
+        # Normalize context configuration to match ace-docs pattern
+        # @param config [Hash] Raw context configuration
+        # @return [Hash] Normalized configuration
+        def self.normalize_context_config(config)
+          # Start with base context config following ace-docs pattern
+          normalized = {
+            "params" => {"format" => "markdown-xml"},
+            "embed_document_source" => true
+          }
+
+          # Merge with provided config
+          config ||= {}
+          normalized.merge!(config)
+
+          # Ensure arrays are properly initialized
+          normalized["presets"] ||= []
+          normalized["files"] ||= []
+          normalized["diffs"] ||= []
+          normalized["commands"] ||= []
+
+          normalized
+        end
+
+        # Build review scope section explaining what will be reviewed
+        # @param subject_config [Hash] Subject configuration
+        # @return [String] Review scope section
+        def self.build_review_scope_section(subject_config)
+          return "" unless subject_config
+
+          # Extract subject description
+          subject_desc = extract_subject_description(subject_config)
+
+          <<~SECTION
+            ## Review Scope
+
+            **Subject of review**:
+            #{subject_desc}
+          SECTION
+        end
+
+        # Extract human-readable description from subject configuration
+        # @param subject_config [Hash] Subject configuration
+        # @return [String] Description string
+        def self.extract_subject_description(subject_config)
+          if subject_config["diff"]
+            "- Git diff changes"
+          elsif subject_config["files"]
+            files = subject_config["files"]
+            if files.is_a?(Array)
+              if files.length == 1
+                "- File: `#{files.first}`"
+              else
+                "- Files: #{files.map { |f| "`#{f}`" }.join(", ")}"
+              end
+            else
+              "- File: `#{files}`"
+            end
+          elsif subject_config["content"]
+            "- Inline content"
+          else
+            "- Repository changes"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/review/molecules/context_extractor.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Review
+    module Molecules
+      # Extracts context (background information) for reviews
+      # Delegates to ContextComposer for context.md pattern and ace-bundle integration
+      class ContextExtractor
+        def initialize
+          @preset_manager = nil # Lazy load to avoid circular dependency
+        end
+
+        # Extract context from configuration
+        # @param context_config [String, Hash, nil] context configuration
+        # @param cache_dir [String, nil] Optional cache directory for context.md
+        # @return [String] extracted context content
+        def extract(context_config, cache_dir = nil)
+          case context_config
+          when nil, "none", false
+            ""
+          when "project", "auto", true
+            extract_project_context(cache_dir)
+          when String
+            extract_from_string(context_config, cache_dir)
+          when Hash
+            extract_from_hash(context_config, cache_dir)
+          else
+            ""
+          end
+        end
+
+        private
+
+        def extract_from_string(input, cache_dir = nil)
+          # Try to parse as YAML first
+          begin
+            parsed = YAML.safe_load(input)
+            return extract_from_hash(parsed, cache_dir) if parsed.is_a?(Hash)
+          rescue Psych::SyntaxError
+            # Continue with string processing
+          end
+
+          # Check if it's an ace-review preset name
+          if preset_context = load_preset_context(input)
+            return extract(preset_context, cache_dir)
+          end
+
+          # Check if it's an ace-bundle preset
+          if ace_bundle_preset_exists?(input)
+            return use_context_composer({"presets" => [input]}, cache_dir)
+          end
+
+          # Treat as file path
+          use_context_composer({"files" => [input]}, cache_dir)
+        end
+
+        def extract_from_hash(config, cache_dir = nil)
+          # Check for ace-review preset reference
+          if config["preset"]
+            if preset_context = load_preset_context(config["preset"])
+              return extract(preset_context, cache_dir)
+            end
+          end
+
+          # Delegate to ContextComposer for context.md pattern
+          use_context_composer(config, cache_dir)
+        end
+
+        def extract_project_context(cache_dir = nil)
+          # Build list of existing project docs from config (ADR-022 pattern)
+          project_docs = Ace::Review.get("project_docs") || default_project_docs
+          existing_docs = project_docs.select { |path| File.exist?(path) }
+
+          if existing_docs.empty?
+            # If no standard docs found, try to find any markdown files
+            existing_docs = Dir.glob("{*.md,docs/*.md}").first(3)
+          end
+
+          return "" if existing_docs.empty?
+
+          # Use ContextComposer to load all docs
+          use_context_composer({"files" => existing_docs}, cache_dir)
+        end
+
+        # Fallback defaults used only when Ace::Review.get("project_docs") returns nil
+        # (e.g., config cascade initialization fails). Primary source is
+        # .ace-defaults/review/config.yml project_docs - keep these in sync.
+        def default_project_docs
+          %w[
+            README.md
+            docs/architecture.md
+            docs/vision.md
+            docs/blueprint.md
+            .github/CONTRIBUTING.md
+            ARCHITECTURE.md
+          ]
+        end
+
+        def load_preset_context(preset_name)
+          # Lazy load preset manager for ace-review presets
+          @preset_manager ||= PresetManager.new
+
+          preset = @preset_manager.load_preset(preset_name)
+          preset&.dig("bundle")
+        end
+
+        def ace_bundle_preset_exists?(preset_name)
+          # Check if this is a valid ace-bundle preset
+          Ace::Bundle.list_presets.any? { |p| p[:name] == preset_name }
+        rescue => e
+          warn "ace-bundle preset check failed: #{e.message}" if Ace::Review.debug?
+          raise e if ENV["ACE_TEST_STRICT"]
+          false
+        end
+
+        def use_context_composer(config, cache_dir = nil)
+          require_relative "context_composer"
+
+          base_instructions = "Load context for code review analysis."
+
+          # Create context.md content
+          context_md = Ace::Review::Molecules::ContextComposer.create_context_md(
+            base_instructions,
+            config
+          )
+
+          # If cache_dir provided, save context.md and load via ace-bundle
+          if cache_dir
+            context_file_path = Ace::Review::Molecules::ContextComposer.save_context_md(
+              context_md,
+              cache_dir
+            )
+
+            # Load via ace-bundle for embedded content
+            Ace::Review::Molecules::ContextComposer.load_context_via_ace_bundle(context_file_path)
+          else
+            # Fallback to direct ace-bundle loading without file
+            begin
+              require "ace/bundle"
+              result = Ace::Bundle.load_auto(context_md, format: "markdown")
+              result.content
+            rescue => e
+              warn "ace-bundle extraction failed: #{e.message}" if Ace::Review.debug?
+              ""
+            end
+          end
+        rescue Ace::Review::Errors::ContextComposerError => e
+          # Fail-fast error handling for ace-bundle failures
+          raise ContextExtractorError, "Context extraction failed: #{e.message}"
+        end
+
+        # Custom error class for ContextExtractor failures
+        class ContextExtractorError < StandardError; end
+      end
+    end
+  end
+end

data/lib/ace/review/molecules/feedback_directory_manager.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Review
+    module Molecules
+      # Manages feedback directory structure and file organization.
+      #
+      # Handles creation of feedback directories, archiving of resolved items,
+      # and listing of feedback files.
+      #
+      # Directory structure:
+      #   {base_path}/
+      #     feedback/
+      #       {id}-{slug}.s.md
+      #       {id}-{slug}.s.md
+      #       _archived/
+      #         {id}-{slug}.s.md
+      #
+      # @example Ensure directories exist
+      #   manager = FeedbackDirectoryManager.new
+      #   manager.ensure_directory("/project")     #=> "/project/feedback"
+      #   manager.ensure_archive("/project")       #=> "/project/feedback/_archived"
+      #
+      # @example Archive a resolved item
+      #   manager.archive("/project/feedback/abc123-bug-fix.s.md")
+      #   #=> { success: true, path: "/project/feedback/_archived/abc123-bug-fix.s.md" }
+      #
+      class FeedbackDirectoryManager
+        # Subdirectory name for feedback files
+        FEEDBACK_DIR = "feedback"
+
+        # Subdirectory name for archived files
+        ARCHIVE_DIR = "_archived"
+
+        # File extension for feedback files
+        FILE_EXTENSION = ".s.md"
+
+        # Get the feedback directory path for a base path
+        #
+        # @param base_path [String] The base project path
+        # @return [String] The feedback directory path
+        def feedback_path(base_path)
+          File.join(base_path, FEEDBACK_DIR)
+        end
+
+        # Get the archive directory path for a base path
+        #
+        # @param base_path [String] The base project path
+        # @return [String] The archive directory path
+        def archive_path(base_path)
+          File.join(base_path, FEEDBACK_DIR, ARCHIVE_DIR)
+        end
+
+        # Ensure the feedback directory exists
+        #
+        # @param base_path [String] The base project path
+        # @return [String] The feedback directory path
+        def ensure_directory(base_path)
+          path = feedback_path(base_path)
+          FileUtils.mkdir_p(path)
+          path
+        end
+
+        # Ensure the archive directory exists
+        #
+        # @param base_path [String] The base project path
+        # @return [String] The archive directory path
+        def ensure_archive(base_path)
+          path = archive_path(base_path)
+          FileUtils.mkdir_p(path)
+          path
+        end
+
+        # Archive a feedback file by moving it to the _archived subdirectory
+        #
+        # @param file_path [String] Path to the feedback file to archive
+        # @return [Hash] Result with :success and :path or :error
+        def archive(file_path)
+          validate_archive_inputs(file_path)
+
+          # Determine the archive destination
+          feedback_dir = File.dirname(file_path)
+          archive_dir = File.join(feedback_dir, ARCHIVE_DIR)
+          filename = File.basename(file_path)
+          dest_path = File.join(archive_dir, filename)
+
+          # Ensure archive directory exists
+          FileUtils.mkdir_p(archive_dir)
+
+          # Move file to archive
+          FileUtils.mv(file_path, dest_path)
+
+          {success: true, path: dest_path}
+        rescue Errno::ENOENT
+          {success: false, error: "File not found: #{file_path}"}
+        rescue Errno::EACCES
+          {success: false, error: "Permission denied: #{file_path}"}
+        rescue => e
+          {success: false, error: "Failed to archive file: #{e.message}"}
+        end
+
+        # List all feedback files in a directory
+        #
+        # @param directory [String] The feedback directory to list
+        # @param include_archived [Boolean] Whether to include archived files (default: false)
+        # @return [Array<String>] Array of file paths
+        def list_files(directory, include_archived: false)
+          return [] unless Dir.exist?(directory)
+
+          files = []
+
+          # List files in main directory (excluding _archived subdirectory)
+          main_files = Dir.glob(File.join(directory, "*#{FILE_EXTENSION}"))
+          files.concat(main_files)
+
+          # Include archived files if requested
+          if include_archived
+            archive_dir = File.join(directory, ARCHIVE_DIR)
+            if Dir.exist?(archive_dir)
+              archived_files = Dir.glob(File.join(archive_dir, "*#{FILE_EXTENSION}"))
+              files.concat(archived_files)
+            end
+          end
+
+          files.sort
+        end
+
+        # Check if a feedback directory exists
+        #
+        # @param base_path [String] The base project path
+        # @return [Boolean] True if feedback directory exists
+        def exists?(base_path)
+          Dir.exist?(feedback_path(base_path))
+        end
+
+        # Check if the archive directory exists
+        #
+        # @param base_path [String] The base project path
+        # @return [Boolean] True if archive directory exists
+        def archive_exists?(base_path)
+          Dir.exist?(archive_path(base_path))
+        end
+
+        # Count feedback files in a directory
+        #
+        # @param directory [String] The feedback directory
+        # @param include_archived [Boolean] Whether to include archived files
+        # @return [Hash] Counts with :active, :archived, and :total keys
+        def count_files(directory)
+          return {active: 0, archived: 0, total: 0} unless Dir.exist?(directory)
+
+          active = Dir.glob(File.join(directory, "*#{FILE_EXTENSION}")).count
+          archived = 0
+
+          archive_dir = File.join(directory, ARCHIVE_DIR)
+          if Dir.exist?(archive_dir)
+            archived = Dir.glob(File.join(archive_dir, "*#{FILE_EXTENSION}")).count
+          end
+
+          {active: active, archived: archived, total: active + archived}
+        end
+
+        private
+
+        # Validate inputs for archive operation
+        #
+        # @param file_path [String] The file path to validate
+        # @raise [ArgumentError] If inputs are invalid
+        def validate_archive_inputs(file_path)
+          raise ArgumentError, "file_path is required" if file_path.nil? || file_path.empty?
+
+          unless file_path.end_with?(FILE_EXTENSION)
+            raise ArgumentError, "file must have #{FILE_EXTENSION} extension"
+          end
+
+          raise ArgumentError, "file does not exist: #{file_path}" unless File.exist?(file_path)
+        end
+      end
+    end
+  end
+end

data/lib/ace/review/molecules/feedback_file_reader.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Review
+    module Molecules
+      # Reads feedback files from disk and parses them into FeedbackItem instances.
+      #
+      # Handles YAML frontmatter parsing and markdown section extraction.
+      # Returns error hashes for malformed files rather than raising exceptions.
+      #
+      # @example Read a single file
+      #   reader = FeedbackFileReader.new
+      #   result = reader.read("/path/to/8o7abc-missing-error.s.md")
+      #   result[:success]       #=> true
+      #   result[:feedback_item] #=> FeedbackItem instance
+      #
+      # @example Read all files in a directory
+      #   reader = FeedbackFileReader.new
+      #   results = reader.read_all("/path/to/feedback")
+      #   results #=> [FeedbackItem, FeedbackItem, ...]
+      #
+      class FeedbackFileReader
+        # YAML frontmatter pattern: content between --- markers at start of file
+        FRONTMATTER_PATTERN = /\A---\n(.*?)\n---\n/m
+
+        # Section header pattern: ## Section Name
+        SECTION_PATTERN = /^## (\w+)\n/
+
+        # Read a single feedback file
+        #
+        # @param file_path [String] Path to the .s.md file
+        # @return [Hash] Result with :success and :feedback_item or :error
+        def read(file_path)
+          validate_file_path(file_path)
+
+          content = File.read(file_path)
+          parse_content(content, file_path)
+        rescue Errno::ENOENT
+          {success: false, error: "File not found: #{file_path}"}
+        rescue Errno::EACCES
+          {success: false, error: "Permission denied: #{file_path}"}
+        rescue ArgumentError => e
+          {success: false, error: e.message}
+        rescue SystemCallError, IOError => e
+          {success: false, error: "Failed to read file: #{e.message}"}
+        end
+
+        # Read all .s.md files in a directory
+        #
+        # @param directory [String] Path to the feedback directory
+        # @return [Array<Models::FeedbackItem>] Array of successfully parsed items
+        def read_all(directory)
+          return [] unless Dir.exist?(directory)
+
+          files = Dir.glob(File.join(directory, "*.s.md"))
+          items = []
+
+          files.each do |file_path|
+            result = read(file_path)
+            items << result[:feedback_item] if result[:success]
+          end
+
+          items
+        end
+
+        # Read feedback files filtered by status
+        #
+        # @param directory [String] Path to the feedback directory
+        # @param status [String] Status to filter by (draft, pending, invalid, skip, done)
+        # @return [Array<Models::FeedbackItem>] Array of matching items
+        def read_by_status(directory, status)
+          read_all(directory).select { |item| item.status == status }
+        end
+
+        private
+
+        # Validate the file path
+        #
+        # @param file_path [String] The file path to validate
+        # @raise [ArgumentError] If path is invalid
+        def validate_file_path(file_path)
+          raise ArgumentError, "file_path is required" if file_path.nil? || file_path.empty?
+        end
+
+        # Parse file content into a FeedbackItem
+        #
+        # @param content [String] The file content
+        # @param file_path [String] The file path (for error messages)
+        # @return [Hash] Result with :success and :feedback_item or :error
+        def parse_content(content, file_path)
+          # Extract frontmatter
+          frontmatter_match = content.match(FRONTMATTER_PATTERN)
+          unless frontmatter_match
+            return {success: false, error: "Missing YAML frontmatter in: #{file_path}"}
+          end
+
+          frontmatter_yaml = frontmatter_match[1]
+          body = content[frontmatter_match.end(0)..]
+
+          # Parse YAML frontmatter
+          frontmatter = parse_frontmatter(frontmatter_yaml, file_path)
+          return frontmatter if frontmatter[:error]
+
+          # Parse markdown sections
+          sections = parse_sections(body)
+
+          # Build FeedbackItem attributes
+          attrs = frontmatter[:data].merge(sections)
+
+          # Create FeedbackItem
+          feedback_item = Models::FeedbackItem.new(attrs)
+          {success: true, feedback_item: feedback_item}
+        rescue ArgumentError => e
+          {success: false, error: "Invalid feedback item in #{file_path}: #{e.message}"}
+        rescue Psych::SyntaxError, TypeError, KeyError => e
+          {success: false, error: "Failed to parse #{file_path}: #{e.message}"}
+        end
+
+        # Parse YAML frontmatter
+        #
+        # @param yaml_content [String] The YAML content
+        # @param file_path [String] The file path (for error messages)
+        # @return [Hash] Result with :data or :error
+        def parse_frontmatter(yaml_content, file_path)
+          data = YAML.safe_load(yaml_content, permitted_classes: [Time, Date])
+
+          unless data.is_a?(Hash)
+            return {error: "Invalid YAML frontmatter in #{file_path}: expected Hash"}
+          end
+
+          {data: data}
+        rescue Psych::SyntaxError => e
+          {error: "YAML syntax error in #{file_path}: #{e.message}"}
+        end
+
+        # Parse markdown sections from the body
+        #
+        # @param body [String] The markdown body after frontmatter
+        # @return [Hash] Hash with section names as keys and content as values
+        def parse_sections(body)
+          sections = {}
+          return sections if body.nil? || body.empty?
+
+          # Split by section headers
+          parts = body.split(SECTION_PATTERN)
+
+          # First part is any content before first section (usually empty)
+          parts.shift if parts.first&.strip&.empty?
+
+          # Process pairs of (section_name, content)
+          parts.each_slice(2) do |name, content|
+            next unless name && content
+
+            key = section_name_to_key(name)
+            sections[key] = content.strip if key
+          end
+
+          sections
+        end
+
+        # Convert section name to attribute key
+        #
+        # @param name [String] The section name (e.g., "Finding", "Context")
+        # @return [String, nil] The attribute key or nil if not recognized
+        def section_name_to_key(name)
+          case name.downcase
+          when "finding" then "finding"
+          when "context" then "context"
+          when "research" then "research"
+          when "resolution" then "resolution"
+          end
+        end
+      end
+    end
+  end
+end