aidp 0.13.0 → 0.14.0

data/lib/aidp/execute/future_work_backlog.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Aidp
+  module Execute
+    # Manages a backlog of future work items discovered during work loops
+    # Captures style violations, technical debt, and refactoring opportunities
+    # that are not directly related to the current feature being implemented
+    class FutureWorkBacklog
+      attr_reader :project_dir, :entries, :current_context
+
+      # Entry types
+      ENTRY_TYPES = {
+        style_violation: "Style Violation",
+        refactor_opportunity: "Refactor Opportunity",
+        technical_debt: "Technical Debt",
+        todo: "TODO",
+        performance: "Performance Issue",
+        security: "Security Concern",
+        documentation: "Documentation Needed"
+      }.freeze
+
+      # Priority levels
+      PRIORITIES = {
+        low: 1,
+        medium: 2,
+        high: 3,
+        critical: 4
+      }.freeze
+
+      def initialize(project_dir, options = {})
+        @project_dir = project_dir
+        @backlog_dir = File.join(project_dir, ".aidp")
+        @backlog_file = options[:backlog_file] || File.join(@backlog_dir, "future_work.yml")
+        @markdown_file = File.join(@backlog_dir, "future_work.md")
+        @entries = []
+        @current_context = {}
+        @options = options
+
+        ensure_backlog_directory
+        load_existing_backlog
+      end
+
+      # Add a new future work entry
+      # @param entry_hash [Hash] Entry details
+      # @option entry_hash [Symbol] :type Entry type (see ENTRY_TYPES)
+      # @option entry_hash [String] :file File path
+      # @option entry_hash [Integer,Range,String] :lines Line number(s)
+      # @option entry_hash [String] :reason Description of the issue
+      # @option entry_hash [String] :recommendation Recommended fix
+      # @option entry_hash [Symbol] :priority Priority level (see PRIORITIES)
+      # @option entry_hash [Hash] :metadata Additional metadata
+      def add_entry(entry_hash)
+        entry = normalize_entry(entry_hash)
+
+        # Avoid duplicates
+        return if duplicate?(entry)
+
+        entry[:id] = generate_entry_id
+        entry[:created_at] = Time.now.utc.iso8601
+        entry[:context] = @current_context.dup
+
+        @entries << entry
+        entry
+      end
+
+      # Set context for subsequent entries (e.g., current work loop, step)
+      def set_context(context_hash)
+        @current_context.merge!(context_hash)
+      end
+
+      # Clear context
+      def clear_context
+        @current_context.clear
+      end
+
+      # Save backlog to disk (both YAML and Markdown)
+      def save
+        save_yaml
+        save_markdown
+      end
+
+      # Get entries filtered by criteria
+      def filter(criteria = {})
+        filtered = @entries
+
+        filtered = filtered.select { |e| e[:type] == criteria[:type] } if criteria[:type]
+        filtered = filtered.select { |e| e[:file] == criteria[:file] } if criteria[:file]
+        filtered = filtered.select { |e| e[:priority] == criteria[:priority] } if criteria[:priority]
+        filtered = filtered.select { |e| e[:context][:work_loop] == criteria[:work_loop] } if criteria[:work_loop]
+
+        filtered
+      end
+
+      # Get entries grouped by type
+      def by_type
+        @entries.group_by { |e| e[:type] }
+      end
+
+      # Get entries grouped by file
+      def by_file
+        @entries.group_by { |e| e[:file] }
+      end
+
+      # Get entries grouped by priority
+      def by_priority
+        @entries.group_by { |e| e[:priority] }.sort_by { |priority, _| -PRIORITIES[priority] }.to_h
+      end
+
+      # Get summary statistics
+      def summary
+        {
+          total: @entries.size,
+          by_type: by_type.transform_values(&:size),
+          by_priority: by_priority.transform_values(&:size),
+          files_affected: @entries.map { |e| e[:file] }.uniq.size
+        }
+      end
+
+      # Mark entry as resolved
+      def resolve_entry(entry_id, resolution_note = nil)
+        entry = @entries.find { |e| e[:id] == entry_id }
+        return unless entry
+
+        entry[:resolved] = true
+        entry[:resolved_at] = Time.now.utc.iso8601
+        entry[:resolution_note] = resolution_note if resolution_note
+      end
+
+      # Remove resolved entries
+      def clear_resolved
+        @entries.reject! { |e| e[:resolved] }
+      end
+
+      # Convert entry to work loop PROMPT.md content
+      def entry_to_prompt(entry_id)
+        entry = @entries.find { |e| e[:id] == entry_id }
+        return unless entry
+
+        <<~PROMPT
+          # Work Loop: #{entry_type_display(entry[:type])}
+
+          ## Task Description
+
+          **File**: #{entry[:file]}
+          **Lines**: #{entry[:lines]}
+          **Priority**: #{entry[:priority].to_s.upcase}
+
+          ## Issue
+
+          #{entry[:reason]}
+
+          ## Recommended Fix
+
+          #{entry[:recommendation]}
+
+          ## Acceptance Criteria
+
+          - [ ] #{entry[:reason]} is resolved
+          - [ ] Code follows LLM_STYLE_GUIDE
+          - [ ] Tests pass
+          - [ ] No new style violations introduced
+
+          ## Original Context
+
+          - Work Loop: #{entry[:context][:work_loop] || "N/A"}
+          - Step: #{entry[:context][:step] || "N/A"}
+          - Created: #{entry[:created_at]}
+
+          ## Completion
+
+          Mark this complete by adding: STATUS: COMPLETE
+        PROMPT
+      end
+
+      # Display summary of backlog
+      def display_summary(output = $stdout)
+        return if @entries.empty?
+
+        output.puts "\n" + "=" * 80
+        output.puts "📝 Future Work Backlog Summary"
+        output.puts "=" * 80
+
+        sum = summary
+        output.puts "\nTotal Items: #{sum[:total]}"
+        output.puts "Files Affected: #{sum[:files_affected]}"
+
+        if sum[:by_type].any?
+          output.puts "\nBy Type:"
+          sum[:by_type].each do |type, count|
+            output.puts "  #{entry_type_display(type)}: #{count}"
+          end
+        end
+
+        if sum[:by_priority].any?
+          output.puts "\nBy Priority:"
+          sum[:by_priority].each do |priority, count|
+            output.puts "  #{priority.to_s.upcase}: #{count}"
+          end
+        end
+
+        output.puts "\n" + "-" * 80
+        output.puts "Review backlog: .aidp/future_work.md"
+        output.puts "Convert to work loop: aidp backlog convert <entry-id>"
+        output.puts "=" * 80 + "\n"
+      end
+
+      private
+
+      # Ensure backlog directory exists
+      def ensure_backlog_directory
+        FileUtils.mkdir_p(@backlog_dir) unless Dir.exist?(@backlog_dir)
+      end
+
+      # Load existing backlog from disk
+      def load_existing_backlog
+        return unless File.exist?(@backlog_file)
+
+        data = YAML.load_file(@backlog_file)
+        @entries = data["entries"] || [] if data.is_a?(Hash)
+        @entries = symbolize_keys_deep(@entries)
+      rescue => e
+        warn "Warning: Could not load existing backlog: #{e.message}"
+        @entries = []
+      end
+
+      # Save backlog to YAML
+      def save_yaml
+        data = {
+          "version" => "1.0",
+          "generated_at" => Time.now.utc.iso8601,
+          "project" => @project_dir,
+          "entries" => @entries.map { |e| stringify_keys_deep(e) }
+        }
+
+        File.write(@backlog_file, YAML.dump(data))
+      end
+
+      # Save backlog to Markdown (human-readable)
+      def save_markdown
+        content = generate_markdown
+
+        File.write(@markdown_file, content)
+      end
+
+      # Generate Markdown representation
+      def generate_markdown
+        lines = []
+        lines << "# Future Work Backlog"
+        lines << ""
+        lines << "Generated: #{Time.now.utc.iso8601}"
+        lines << "Project: #{@project_dir}"
+        lines << ""
+
+        sum = summary
+        lines << "## Summary"
+        lines << ""
+        lines << "- **Total Items**: #{sum[:total]}"
+        lines << "- **Files Affected**: #{sum[:files_affected]}"
+        lines << ""
+
+        # Group by priority
+        by_priority.each do |priority, entries|
+          lines << "## #{priority.to_s.upcase} Priority (#{entries.size})"
+          lines << ""
+
+          # Group by type within priority
+          entries.group_by { |e| e[:type] }.each do |type, type_entries|
+            lines << "### #{entry_type_display(type)}"
+            lines << ""
+
+            type_entries.each do |entry|
+              lines << format_entry_markdown(entry)
+              lines << ""
+            end
+          end
+        end
+
+        lines << "---"
+        lines << ""
+        lines << "## Usage"
+        lines << ""
+        lines << "Convert an entry to a work loop:"
+        lines << "```bash"
+        lines << "aidp backlog convert <entry-id>"
+        lines << "```"
+        lines << ""
+
+        lines.join("\n")
+      end
+
+      # Format single entry as Markdown
+      def format_entry_markdown(entry)
+        lines = []
+        lines << "#### #{entry[:id]} - #{entry[:file]}"
+        lines << ""
+        lines << "**Lines**: #{entry[:lines]}"
+        lines << ""
+        lines << "**Issue**: #{entry[:reason]}"
+        lines << ""
+        lines << "**Recommendation**: #{entry[:recommendation]}"
+        lines << ""
+
+        if entry[:context].any?
+          lines << "**Context**: Work Loop: #{entry[:context][:work_loop] || "N/A"}, Step: #{entry[:context][:step] || "N/A"}"
+          lines << ""
+        end
+
+        lines << "*Created: #{entry[:created_at]}*"
+
+        lines.join("\n")
+      end
+
+      # Normalize entry hash
+      def normalize_entry(entry_hash)
+        {
+          type: entry_hash[:type] || :technical_debt,
+          file: normalize_path(entry_hash[:file]),
+          lines: normalize_lines(entry_hash[:lines]),
+          reason: entry_hash[:reason] || "No reason provided",
+          recommendation: entry_hash[:recommendation] || "No recommendation provided",
+          priority: entry_hash[:priority] || :medium,
+          metadata: entry_hash[:metadata] || {},
+          resolved: false
+        }
+      end
+
+      # Check if entry is duplicate
+      def duplicate?(entry)
+        @entries.any? do |existing|
+          existing[:file] == entry[:file] &&
+            existing[:lines] == entry[:lines] &&
+            existing[:reason] == entry[:reason] &&
+            !existing[:resolved]
+        end
+      end
+
+      # Generate unique entry ID
+      def generate_entry_id
+        timestamp = Time.now.to_i
+        random = SecureRandom.hex(4)
+        "fw-#{timestamp}-#{random}"
+      end
+
+      # Normalize file path (relative to project)
+      def normalize_path(file_path)
+        return file_path unless file_path
+
+        path = Pathname.new(file_path)
+        project = Pathname.new(@project_dir)
+
+        if path.absolute?
+          path.relative_path_from(project).to_s
+        else
+          path.to_s
+        end
+      rescue ArgumentError
+        file_path
+      end
+
+      # Normalize line numbers
+      def normalize_lines(lines)
+        case lines
+        when Integer
+          lines.to_s
+        when Range
+          "#{lines.begin}-#{lines.end}"
+        when String
+          lines
+        else
+          "unknown"
+        end
+      end
+
+      # Get display name for entry type
+      def entry_type_display(type)
+        ENTRY_TYPES[type] || type.to_s.split("_").map(&:capitalize).join(" ")
+      end
+
+      # Recursively symbolize keys
+      def symbolize_keys_deep(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            result[key.to_sym] = symbolize_keys_deep(value)
+          end
+        when Array
+          obj.map { |item| symbolize_keys_deep(item) }
+        else
+          obj
+        end
+      end
+
+      # Recursively stringify keys
+      def stringify_keys_deep(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            result[key.to_s] = stringify_keys_deep(value)
+          end
+        when Array
+          obj.map { |item| stringify_keys_deep(item) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/aidp/execute/guard_policy.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Aidp
+  module Execute
+    # Enforces safety constraints during work loops
+    # Responsibilities:
+    # - Check file patterns (include/exclude globs)
+    # - Enforce max lines changed per commit
+    # - Track files requiring confirmation
+    # - Validate changes against policy before execution
+    class GuardPolicy
+      attr_reader :config, :project_dir
+
+      def initialize(project_dir, config)
+        @project_dir = project_dir
+        @config = config
+        @confirmed_files = Set.new
+      end
+
+      # Check if guards are enabled
+      def enabled?
+        config.dig(:enabled) == true
+      end
+
+      # Validate if a file can be modified
+      # Returns { allowed: true/false, reason: string }
+      def can_modify_file?(file_path)
+        return {allowed: true} unless enabled?
+
+        normalized_path = normalize_path(file_path)
+
+        # Check exclude patterns first
+        if excluded?(normalized_path)
+          return {
+            allowed: false,
+            reason: "File matches exclude pattern in guards configuration"
+          }
+        end
+
+        # Check include patterns (if specified, file must match at least one)
+        if has_include_patterns? && !included?(normalized_path)
+          return {
+            allowed: false,
+            reason: "File does not match any include pattern in guards configuration"
+          }
+        end
+
+        # Check if file requires confirmation
+        if requires_confirmation?(normalized_path) && !confirmed?(normalized_path)
+          return {
+            allowed: false,
+            reason: "File requires one-time confirmation before modification",
+            requires_confirmation: true,
+            file_path: normalized_path
+          }
+        end
+
+        {allowed: true}
+      end
+
+      # Confirm a file for modification (one-time confirmation)
+      def confirm_file(file_path)
+        normalized_path = normalize_path(file_path)
+        @confirmed_files.add(normalized_path)
+      end
+
+      # Check if total lines changed exceeds limit
+      # diff_stats: { file_path => { additions: n, deletions: n } }
+      def validate_changes(diff_stats)
+        return {valid: true} unless enabled?
+
+        errors = []
+
+        # Check max lines per commit
+        if (max_lines = config.dig(:max_lines_per_commit))
+          total_changes = calculate_total_changes(diff_stats)
+
+          if total_changes > max_lines
+            errors << "Total lines changed (#{total_changes}) exceeds limit (#{max_lines})"
+          end
+        end
+
+        # Check each file against policy
+        diff_stats.each do |file_path, stats|
+          result = can_modify_file?(file_path)
+          unless result[:allowed]
+            errors << "#{file_path}: #{result[:reason]}"
+          end
+        end
+
+        if errors.any?
+          {valid: false, errors: errors}
+        else
+          {valid: true}
+        end
+      end
+
+      # Get list of files requiring confirmation
+      def files_requiring_confirmation
+        return [] unless enabled?
+
+        patterns = config.dig(:confirm_files) || []
+        patterns.map { |pattern| expand_glob_pattern(pattern) }.flatten.compact
+      end
+
+      # Check if file requires confirmation
+      def requires_confirmation?(file_path)
+        return false unless enabled?
+
+        patterns = config.dig(:confirm_files) || []
+        normalized_path = normalize_path(file_path)
+
+        patterns.any? { |pattern| matches_pattern?(normalized_path, pattern) }
+      end
+
+      # Check if file has been confirmed
+      def confirmed?(file_path)
+        normalized_path = normalize_path(file_path)
+        @confirmed_files.include?(normalized_path)
+      end
+
+      # Get summary of guard policy configuration
+      def summary
+        return {enabled: false} unless enabled?
+
+        {
+          enabled: true,
+          include_patterns: config.dig(:include_files) || [],
+          exclude_patterns: config.dig(:exclude_files) || [],
+          confirm_patterns: config.dig(:confirm_files) || [],
+          max_lines_per_commit: config.dig(:max_lines_per_commit),
+          confirmed_files: @confirmed_files.to_a
+        }
+      end
+
+      # Bypass guards (for specific use cases like testing)
+      def bypass?
+        ENV["AIDP_BYPASS_GUARDS"] == "1" || config.dig(:bypass) == true
+      end
+
+      # Enable guards (override bypass)
+      def enable!
+        config[:enabled] = true
+      end
+
+      # Disable guards
+      def disable!
+        config[:enabled] = false
+      end
+
+      private
+
+      # Normalize file path relative to project directory
+      def normalize_path(file_path)
+        path = Pathname.new(file_path)
+        project = Pathname.new(@project_dir)
+
+        if path.absolute?
+          path.relative_path_from(project).to_s
+        else
+          path.to_s
+        end
+      rescue ArgumentError
+        # Path is outside project directory
+        file_path
+      end
+
+      # Check if file matches exclude patterns
+      def excluded?(file_path)
+        patterns = config.dig(:exclude_files) || []
+        patterns.any? { |pattern| matches_pattern?(file_path, pattern) }
+      end
+
+      # Check if file matches include patterns
+      def included?(file_path)
+        patterns = config.dig(:include_files) || []
+        patterns.any? { |pattern| matches_pattern?(file_path, pattern) }
+      end
+
+      # Check if include patterns are configured
+      def has_include_patterns?
+        patterns = config.dig(:include_files) || []
+        patterns.any?
+      end
+
+      # Match file path against glob pattern
+      # Uses File.fnmatch for safe, efficient pattern matching without ReDoS risk
+      def matches_pattern?(file_path, pattern)
+        # Ruby's File.fnmatch with FNM_EXTGLOB handles most patterns safely
+        # FNM_EXTGLOB enables {a,b} brace expansion
+        # For ** patterns, we need to handle them specially as fnmatch doesn't support ** natively
+
+        if pattern.include?("**")
+          # Convert ** to * for fnmatch compatibility and check if path contains the pattern parts
+          # Pattern like "lib/**/*.rb" should match "lib/foo/bar.rb"
+          pattern_parts = pattern.split("**").map(&:strip).reject(&:empty?)
+
+          if pattern_parts.empty?
+            # Pattern is just "**" - matches everything
+            true
+          elsif pattern_parts.size == 1
+            # Pattern like "**/file.rb" or "lib/**"
+            part = pattern_parts[0].sub(%r{^/}, "").sub(%r{/$}, "")
+            if pattern.start_with?("**")
+              # Matches if any part of the path matches
+              File.fnmatch(part, file_path, File::FNM_EXTGLOB) ||
+                File.fnmatch("**/#{part}", file_path, File::FNM_EXTGLOB) ||
+                file_path.end_with?(part) ||
+                file_path.include?("/#{part}")
+            else
+              # Pattern ends with **: match prefix
+              file_path.start_with?(part)
+            end
+          else
+            # Pattern like "lib/**/*.rb" - has prefix and suffix
+            prefix = pattern_parts[0].sub(%r{/$}, "")
+            suffix = pattern_parts[1].sub(%r{^/}, "")
+
+            file_path.start_with?(prefix) && File.fnmatch(suffix, file_path.sub(/^#{Regexp.escape(prefix)}\//, ""), File::FNM_EXTGLOB)
+          end
+        else
+          # Standard glob pattern - use File.fnmatch which is safe from ReDoS
+          # FNM_DOTMATCH allows * to match files starting with .
+          File.fnmatch(pattern, file_path, File::FNM_EXTGLOB | File::FNM_DOTMATCH)
+        end
+      end
+
+      # Expand glob pattern to actual files (for confirmation list)
+      def expand_glob_pattern(pattern)
+        Dir.glob(File.join(@project_dir, pattern), File::FNM_DOTMATCH).map do |file|
+          next if File.directory?(file)
+          normalize_path(file)
+        end
+      end
+
+      # Calculate total lines changed from diff stats
+      def calculate_total_changes(diff_stats)
+        diff_stats.values.sum do |stats|
+          (stats[:additions] || 0) + (stats[:deletions] || 0)
+        end
+      end
+    end
+  end
+end