ace-idea 0.18.0

data/lib/ace/idea/molecules/idea_doctor_reporter.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Idea
+    module Molecules
+      # Formats doctor diagnosis results for terminal, JSON, or summary output.
+      class IdeaDoctorReporter
+        COLORS = {
+          red: "\e[31m",
+          yellow: "\e[33m",
+          green: "\e[32m",
+          blue: "\e[34m",
+          cyan: "\e[36m",
+          reset: "\e[0m",
+          bold: "\e[1m"
+        }.freeze
+
+        ICONS = {
+          error: "❌",
+          warning: "⚠️",
+          info: "ℹ️",
+          success: "✅",
+          doctor: "🏥",
+          stats: "📊",
+          search: "🔍",
+          fix: "🔧",
+          score: "📈"
+        }.freeze
+
+        # Format diagnosis results
+        # @param results [Hash] Results from IdeaDoctor#run_diagnosis
+        # @param format [Symbol] Output format (:terminal, :json, :summary)
+        # @param verbose [Boolean] Show verbose output
+        # @param colors [Boolean] Enable colored output
+        # @return [String] Formatted output
+        def self.format_results(results, format: :terminal, verbose: false, colors: true)
+          case format.to_sym
+          when :json
+            format_json(results)
+          when :summary
+            format_summary(results, colors: colors)
+          else
+            format_terminal(results, verbose: verbose, colors: colors)
+          end
+        end
+
+        # Format auto-fix results
+        # @param fix_results [Hash] Results from IdeaDoctorFixer#fix_issues
+        # @param colors [Boolean] Enable colored output
+        # @return [String] Formatted fix output
+        def self.format_fix_results(fix_results, colors: true)
+          output = []
+
+          output << if fix_results[:dry_run]
+            "\n#{colorize("#{ICONS[:search]} DRY RUN MODE", :cyan, colors)} - No changes applied"
+          else
+            "\n#{colorize("#{ICONS[:fix]} Auto-Fix Applied", :green, colors)}"
+          end
+
+          if fix_results[:fixed] > 0
+            output << "#{colorize("Fixed:", :green, colors)} #{fix_results[:fixed]} issues"
+
+            if fix_results[:fixes_applied]&.any?
+              output << "\nFixes applied:"
+              fix_results[:fixes_applied].each do |fix|
+                output << "  #{colorize("✓", :green, colors)} #{fix[:description]}"
+                output << "    #{colorize(fix[:file], :blue, colors)}" if fix[:file]
+              end
+            end
+          end
+
+          if fix_results[:skipped] > 0
+            output << "#{colorize("Skipped:", :yellow, colors)} #{fix_results[:skipped]} issues (manual fix required)"
+          end
+
+          output.join("\n")
+        end
+
+        class << self
+          private
+
+          def format_terminal(results, verbose: false, colors: true)
+            output = []
+
+            # Header
+            output << "\n#{colorize("#{ICONS[:doctor]} Idea Health Check", :bold, colors)}"
+            output << "=" * 40
+
+            # Stats overview
+            if results[:stats]
+              output << "\n#{colorize("#{ICONS[:stats]} Overview", :cyan, colors)}"
+              output << "-" * 20
+              output << "  Ideas scanned: #{results[:stats][:ideas_scanned]}"
+              output << "  Folders checked: #{results[:stats][:folders_checked]}"
+            end
+
+            # Issues
+            if results[:issues]&.any?
+              output << "\n#{colorize("Issues Found:", :yellow, colors)}"
+              output << "-" * 20
+              output.concat(format_issues(results[:issues], verbose, colors))
+            else
+              output << "\n#{colorize("#{ICONS[:success]} All ideas healthy", :green, colors)}"
+            end
+
+            # Health Score
+            output << "\n#{colorize("#{ICONS[:score]} Health Score:", :bold, colors)} #{format_health_score(results[:health_score], colors)}"
+            output << "=" * 40
+
+            # Summary
+            if results[:stats]
+              output << format_issue_summary(results[:stats], colors)
+            end
+
+            # Duration
+            if results[:duration]
+              output << "\n#{colorize("Completed in #{format_duration(results[:duration])}", :blue, colors)}"
+            end
+
+            output.join("\n")
+          end
+
+          def format_summary(results, colors: true)
+            output = []
+
+            health_status = if results[:health_score] >= 90
+              colorize("Excellent", :green, colors)
+            elsif results[:health_score] >= 70
+              colorize("Good", :yellow, colors)
+            elsif results[:health_score] >= 50
+              colorize("Fair", :yellow, colors)
+            else
+              colorize("Poor", :red, colors)
+            end
+
+            output << "Health: #{health_status} (#{results[:health_score]}/100)"
+
+            if results[:stats]
+              errors = results[:stats][:errors] || 0
+              warnings = results[:stats][:warnings] || 0
+
+              output << colorize("Errors: #{errors}", :red, colors) if errors > 0
+              output << colorize("Warnings: #{warnings}", :yellow, colors) if warnings > 0
+            end
+
+            output.join(" | ")
+          end
+
+          def format_json(results)
+            clean = {
+              health_score: results[:health_score],
+              valid: results[:valid],
+              errors: [],
+              warnings: [],
+              info: [],
+              stats: results[:stats],
+              duration: results[:duration],
+              root_path: results[:root_path]
+            }
+
+            if results[:issues]
+              results[:issues].each do |issue|
+                category = case issue[:type]
+                when :error then :errors
+                when :warning then :warnings
+                else :info
+                end
+                clean[category] << {
+                  message: issue[:message],
+                  location: issue[:location]
+                }
+              end
+            end
+
+            JSON.pretty_generate(clean)
+          end
+
+          def format_issues(issues, verbose, colors)
+            output = []
+            grouped = issues.group_by { |i| i[:type] }
+
+            if grouped[:error]
+              output << "\n#{colorize("#{ICONS[:error]} Errors (#{grouped[:error].size})", :red, colors)}"
+              grouped[:error].each_with_index do |issue, i|
+                output << format_issue(issue, i + 1, colors)
+              end
+            end
+
+            if grouped[:warning]
+              output << "\n#{colorize("#{ICONS[:warning]} Warnings (#{grouped[:warning].size})", :yellow, colors)}"
+              if verbose || grouped[:warning].size <= 10
+                grouped[:warning].each_with_index do |issue, i|
+                  output << format_issue(issue, i + 1, colors)
+                end
+              else
+                grouped[:warning].first(5).each_with_index do |issue, i|
+                  output << format_issue(issue, i + 1, colors)
+                end
+                output << "  ... and #{grouped[:warning].size - 5} more warnings (use --verbose to see all)"
+              end
+            end
+
+            output
+          end
+
+          def format_issue(issue, number, colors)
+            location = issue[:location] ? " (#{colorize(issue[:location], :blue, colors)})" : ""
+            "#{number}. #{issue[:message]}#{location}"
+          end
+
+          def format_health_score(score, colors)
+            color = if score >= 90
+              :green
+            elsif score >= 70
+              :yellow
+            else
+              :red
+            end
+
+            status = if score >= 90
+              "Excellent"
+            elsif score >= 70
+              "Good"
+            elsif score >= 50
+              "Fair"
+            else
+              "Poor"
+            end
+
+            "#{colorize("#{score}/100", color, colors)} (#{status})"
+          end
+
+          def format_issue_summary(stats, colors)
+            parts = []
+            parts << colorize("#{stats[:errors]} errors", :red, colors) if stats[:errors] > 0
+            parts << colorize("#{stats[:warnings]} warnings", :yellow, colors) if stats[:warnings] > 0
+
+            if parts.empty?
+              colorize("No issues found", :green, colors)
+            else
+              parts.join(", ")
+            end
+          end
+
+          def format_duration(duration)
+            if duration < 1
+              "#{(duration * 1000).round}ms"
+            else
+              "#{duration.round(2)}s"
+            end
+          end
+
+          def colorize(text, color, enabled = true)
+            return text unless enabled && COLORS[color]
+
+            "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/molecules/idea_frontmatter_validator.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/support/items"
+require_relative "../atoms/idea_validation_rules"
+require_relative "../atoms/idea_id_formatter"
+
+module Ace
+  module Idea
+    module Molecules
+      # Validates idea spec file frontmatter for correctness and completeness.
+      # Returns an array of issue hashes with :type, :message, and :location keys.
+      class IdeaFrontmatterValidator
+        # Validate a single idea spec file
+        # @param file_path [String] Path to the .idea.s.md file
+        # @param special_folder [String, nil] Special folder the idea is in
+        # @return [Array<Hash>] List of issues found
+        def self.validate(file_path, special_folder: nil)
+          issues = []
+
+          unless File.exist?(file_path)
+            issues << {type: :error, message: "File does not exist", location: file_path}
+            return issues
+          end
+
+          content = File.read(file_path)
+
+          # Check delimiters
+          validate_delimiters(content, file_path, issues)
+          return issues if issues.any? { |i| i[:type] == :error }
+
+          # Parse frontmatter
+          frontmatter = parse_frontmatter(content, file_path, issues)
+          return issues unless frontmatter
+
+          # Validate required fields
+          validate_required_fields(frontmatter, file_path, issues)
+
+          # Validate field values
+          validate_field_values(frontmatter, file_path, issues)
+
+          # Validate recommended fields
+          validate_recommended_fields(frontmatter, file_path, content, issues)
+
+          # Validate scope/status consistency
+          validate_scope_consistency(frontmatter, special_folder, file_path, issues)
+
+          issues
+        end
+
+        class << self
+          private
+
+          def validate_delimiters(content, file_path, issues)
+            lines = content.lines
+
+            unless lines.first&.strip == "---"
+              issues << {type: :error, message: "Missing opening '---' delimiter", location: file_path}
+              return
+            end
+
+            # Find closing delimiter (skip first line)
+            has_closing = lines[1..].any? { |line| line.strip == "---" }
+            unless has_closing
+              issues << {type: :error, message: "Missing closing '---' delimiter", location: file_path}
+            end
+          end
+
+          def parse_frontmatter(content, file_path, issues)
+            frontmatter, _body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+
+            if frontmatter.nil? || !frontmatter.is_a?(Hash)
+              issues << {type: :error, message: "Failed to parse YAML frontmatter", location: file_path}
+              return nil
+            end
+
+            frontmatter
+          rescue Psych::SyntaxError => e
+            issues << {type: :error, message: "YAML syntax error: #{e.message}", location: file_path}
+            nil
+          end
+
+          def validate_required_fields(frontmatter, file_path, issues)
+            missing = Atoms::IdeaValidationRules.missing_required_fields(frontmatter)
+
+            missing.each do |field|
+              severity = (field == "title") ? :warning : :error
+              issues << {type: severity, message: "Missing required field: #{field}", location: file_path}
+            end
+          end
+
+          def validate_field_values(frontmatter, file_path, issues)
+            # Validate ID format
+            if frontmatter["id"] && !Atoms::IdeaValidationRules.valid_id?(frontmatter["id"].to_s)
+              issues << {type: :error, message: "Invalid idea ID format: '#{frontmatter["id"]}'", location: file_path}
+            end
+
+            # Validate status value
+            if frontmatter["status"] && !Atoms::IdeaValidationRules.valid_status?(frontmatter["status"])
+              issues << {type: :error, message: "Invalid status value: '#{frontmatter["status"]}'", location: file_path}
+            end
+
+            # Validate tags is an array
+            if frontmatter.key?("tags") && !frontmatter["tags"].is_a?(Array)
+              issues << {type: :warning, message: "Field 'tags' is not an array", location: file_path}
+            end
+
+            if frontmatter.key?("location")
+              issues << {type: :warning, message: "Derived field 'location' should not be stored in frontmatter", location: file_path}
+            end
+          end
+
+          def validate_recommended_fields(frontmatter, file_path, content, issues)
+            missing = Atoms::IdeaValidationRules.missing_recommended_fields(frontmatter)
+
+            missing.each do |field|
+              issues << {type: :warning, message: "Missing recommended field: #{field}", location: file_path}
+            end
+          end
+
+          def validate_scope_consistency(frontmatter, special_folder, file_path, issues)
+            return unless frontmatter["status"]
+
+            scope_issues = Atoms::IdeaValidationRules.scope_consistent?(
+              frontmatter["status"],
+              special_folder
+            )
+
+            scope_issues.each do |issue|
+              issues << issue.merge(location: file_path)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/molecules/idea_llm_enhancer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Idea
+    module Molecules
+      # Enhances ideas with LLM to produce the 3-Question Brief structure.
+      # System prompt is hardcoded for this iteration (as specified by task 291.01).
+      #
+      # 3-Question Brief structure:
+      # - What I Hope to Accomplish
+      # - What "Complete" Looks Like
+      # - Success Criteria
+      class IdeaLlmEnhancer
+        # Hardcoded system prompt for 3-Question Brief generation
+        SYSTEM_PROMPT = <<~PROMPT
+          You are an assistant that helps structure raw software development ideas into clear, actionable briefs.
+
+          Given a raw idea, produce a structured response as a JSON object with these fields:
+          - "title": a concise, clear title for the idea (max 60 chars)
+          - "enhanced_content": the full enhanced idea in markdown with exactly these 3 sections:
+            ## What I Hope to Accomplish
+            (The desired impact or outcome - why this matters)
+
+            ## What "Complete" Looks Like
+            (A concrete end state that would indicate this idea is fully realized)
+
+            ## Success Criteria
+            (Verifiable checks that confirm success - use bullet points)
+
+          Keep it concise and actionable. Respond with valid JSON only.
+        PROMPT
+
+        # @param config [Hash] Configuration hash (may contain llm_model)
+        def initialize(config: {})
+          @config = config
+          @model = config.dig("idea", "llm_model") ||
+            config["llm_model"] ||
+            "gflash"
+        end
+
+        # Enhance content using LLM
+        # @param content [String] Raw idea content
+        # @return [Hash] Result with :success, :content (on success), :error (on failure)
+        def enhance(content)
+          return fallback_enhancement(content) unless llm_available?
+
+          result = call_llm(content)
+          if result[:success]
+            format_enhanced(result[:data], content)
+          else
+            fallback_enhancement(content)
+          end
+        rescue => e
+          fallback_enhancement(content, error: e.message)
+        end
+
+        private
+
+        def llm_available?
+          # Check if ace-llm is loadable
+          require "ace/llm/query_interface"
+          true
+        rescue LoadError
+          false
+        end
+
+        def call_llm(content)
+          require "ace/llm/query_interface"
+
+          prompt = "Structure this idea into a 3-Question Brief:\n\n#{content}"
+
+          response = Ace::LLM::QueryInterface.query(
+            @model,
+            prompt,
+            system: SYSTEM_PROMPT,
+            temperature: 0.3,
+            max_tokens: 2000
+          )
+
+          if response[:text]
+            text = response[:text].strip
+            # Extract JSON from optional markdown code block (handles preamble text)
+            if (m = text.match(/```(?:json)?\s*\n?(.*?)\n?```/m))
+              text = m[1].strip
+            end
+
+            data = JSON.parse(text)
+            {success: true, data: data}
+          else
+            {success: false, error: "No text in LLM response"}
+          end
+        rescue JSON::ParserError => e
+          {success: false, error: "Invalid JSON from LLM: #{e.message}"}
+        rescue => e
+          {success: false, error: e.message}
+        end
+
+        def format_enhanced(data, _original_content)
+          title = data["title"] || "Untitled Idea"
+          enhanced = data["enhanced_content"] || generate_stub_content(_original_content)
+
+          content = "# #{title}\n\n#{enhanced}"
+
+          {success: true, content: content, title: title}
+        end
+
+        def fallback_enhancement(content, error: nil)
+          title = extract_title(content)
+
+          # Build stub structure
+          body = []
+          body << "# #{title}"
+          body << ""
+          body << "## What I Hope to Accomplish"
+          body << ""
+          body << "_[What impact should this have? Why does it matter?]_"
+          body << ""
+          body << "## What \"Complete\" Looks Like"
+          body << ""
+          body << "_[What concrete end state would indicate this idea is fully realized?]_"
+          body << ""
+          body << "## Success Criteria"
+          body << ""
+          body << "_[What verifiable checks would confirm success?]_"
+          body << ""
+          body << "---"
+          body << ""
+          body << "## Original Idea"
+          body << ""
+          body << content.strip
+
+          enhanced_content = body.join("\n")
+
+          if error
+            {success: true, content: enhanced_content, fallback: true, error: error}
+          else
+            {success: true, content: enhanced_content, fallback: true}
+          end
+        end
+
+        def generate_stub_content(content)
+          <<~STUB
+            ## What I Hope to Accomplish
+
+            _[What impact should this have? Why does it matter?]_
+
+            ## What "Complete" Looks Like
+
+            _[What concrete end state would indicate this idea is fully realized?]_
+
+            ## Success Criteria
+
+            _[What verifiable checks would confirm success?]_
+
+            ---
+
+            ## Original Idea
+
+            #{content.strip}
+          STUB
+        end
+
+        def extract_title(content)
+          return "Untitled Idea" if content.nil? || content.strip.empty?
+
+          match = content.match(/^#\s+(.+)$/)
+          return match[1].strip if match
+
+          first_line = content.split("\n").first&.strip || ""
+          first_line.empty? ? "Untitled Idea" : first_line[0..59]
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/molecules/idea_loader.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../atoms/idea_file_pattern"
+require_relative "../atoms/idea_frontmatter_defaults"
+require_relative "../models/idea"
+
+# Shared atoms from ace-support-items
+require "ace/support/items"
+
+module Ace
+  module Idea
+    module Molecules
+      # Loads an idea from its directory, parsing frontmatter + body,
+      # and enumerating attachments (images, files).
+      class IdeaLoader
+        # Load an idea from a ScanResult
+        # @param scan_result [ScanResult] Scan result pointing to the idea directory
+        # @return [Idea, nil] Loaded idea or nil if load fails
+        def self.from_scan_result(scan_result)
+          new.load(scan_result.dir_path,
+            id: scan_result.id,
+            special_folder: scan_result.special_folder)
+        end
+
+        # Load an idea from a directory path
+        # @param dir_path [String] Path to the idea directory
+        # @param id [String, nil] Known ID (extracted from folder name if nil)
+        # @param special_folder [String, nil] Known special folder
+        # @return [Idea, nil] Loaded idea or nil
+        def load(dir_path, id: nil, special_folder: nil)
+          return nil unless Dir.exist?(dir_path)
+
+          # Find the spec file
+          spec_file = Dir.glob(File.join(dir_path, Atoms::IdeaFilePattern::FILE_GLOB)).first
+          return nil unless spec_file
+
+          # Extract ID from folder name if not provided
+          folder_name = File.basename(dir_path)
+          id ||= extract_id(folder_name)
+
+          # Parse the spec file
+          content = File.read(spec_file)
+          frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+
+          # Enumerate attachments (all non-.idea.s.md files in the directory)
+          attachments = list_attachments(dir_path)
+
+          # Extract title from frontmatter or body header
+          title = frontmatter["title"] || Ace::Support::Items::Atoms::TitleExtractor.extract(body) || folder_name
+
+          # Parse creation time
+          created_at = parse_created_at(frontmatter["created_at"], id)
+
+          # Extract known fields, preserve others in metadata
+          known_keys = %w[id status title tags created_at]
+          extra_metadata = frontmatter.reject { |k, _| known_keys.include?(k) }
+
+          Models::Idea.new(
+            id: id || frontmatter["id"],
+            status: normalize_status(frontmatter["status"] || "pending"),
+            title: title,
+            tags: Array(frontmatter["tags"]),
+            content: body.to_s.strip,
+            path: dir_path,
+            file_path: spec_file,
+            special_folder: special_folder,
+            created_at: created_at,
+            attachments: attachments,
+            metadata: extra_metadata
+          )
+        rescue
+          nil
+        end
+
+        private
+
+        def extract_id(folder_name)
+          match = folder_name.match(/^([0-9a-z]{6})/)
+          match ? match[1] : nil
+        end
+
+        def list_attachments(dir_path)
+          Dir.glob(File.join(dir_path, "*"))
+            .select { |f| File.file?(f) }
+            .reject { |f| f.end_with?(Atoms::IdeaFilePattern::FILE_EXTENSION) }
+            .map { |f| File.basename(f) }
+            .reject { |name| name.start_with?(".") }  # skip hidden OS files (.DS_Store etc)
+            .sort
+        end
+
+        def parse_created_at(value, id)
+          return Time.now if value.nil?
+
+          case value
+          when Time then value
+          when String
+            begin
+              Time.parse(value)
+            rescue ArgumentError
+              id ? decode_time_from_id(id) : Time.now
+            end
+          else
+            Time.now
+          end
+        end
+
+        def decode_time_from_id(id)
+          require "ace/b36ts"
+          Ace::B36ts.decode(id)
+        rescue
+          Time.now
+        end
+
+        def normalize_status(status)
+          value = status.to_s
+          return "obsolete" if value == "cancelled"
+
+          value
+        end
+      end
+    end
+  end
+end