ace-idea 0.18.0

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "ace/support/items"
+
+module Ace
+  module Idea
+    module Molecules
+      # Moves idea folders to different locations within the ideas root directory.
+      # Delegates to SpecialFolderDetector for folder name normalization.
+      class IdeaMover
+        # @param root_dir [String] Root directory for ideas
+        def initialize(root_dir)
+          @root_dir = root_dir
+        end
+
+        # Move an idea folder to a target location
+        # @param idea [Idea] Idea to move
+        # @param to [String] Target folder name (short or full, e.g., "maybe", "_archive")
+        # @param date [Time, nil] Date used to compute archive partition (default: Time.now)
+        # @return [String] New path of the idea directory
+        def move(idea, to:, date: nil)
+          normalized = Ace::Support::Items::Atoms::SpecialFolderDetector.normalize(to)
+
+          target_parent = if normalized == "_archive"
+            partition = Ace::Support::Items::Atoms::DatePartitionPath.compute(date || Time.now)
+            File.expand_path(File.join(@root_dir, normalized, partition))
+          else
+            File.expand_path(File.join(@root_dir, normalized))
+          end
+
+          root_real = File.expand_path(@root_dir)
+          unless target_parent.start_with?(root_real + File::SEPARATOR)
+            raise ArgumentError, "Path traversal detected in --to option"
+          end
+          FileUtils.mkdir_p(target_parent)
+
+          folder_name = File.basename(idea.path)
+          new_path = File.join(target_parent, folder_name)
+
+          # Same-location no-op check
+          return idea.path if File.expand_path(idea.path) == File.expand_path(new_path)
+
+          atomic_move(idea.path, new_path)
+        end
+
+        # Move an idea to root (remove from special folder)
+        # @param idea [Idea] Idea to move
+        # @return [String] New path of the idea directory
+        def move_to_root(idea)
+          folder_name = File.basename(idea.path)
+          new_path = File.join(@root_dir, folder_name)
+
+          # Same-location no-op check
+          return idea.path if File.expand_path(idea.path) == File.expand_path(new_path)
+
+          atomic_move(idea.path, new_path)
+        end
+
+        private
+
+        # Move src to dest, raising ArgumentError if dest already exists.
+        def atomic_move(src, dest)
+          raise ArgumentError, "Destination already exists: #{dest}" if File.exist?(dest)
+
+          begin
+            File.rename(src, dest)
+          rescue Errno::EXDEV
+            # Cross-device: fall back to copy+remove
+            FileUtils.cp_r(src, dest)
+            FileUtils.rm_rf(src)
+          end
+          dest
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+require_relative "idea_scanner"
+
+module Ace
+  module Idea
+    module Molecules
+      # Wraps ShortcutResolver for raw idea IDs (no .t. type marker).
+      # Resolves 3-char suffix shortcuts, full 6-char IDs.
+      # Explicitly detects and warns on ambiguity collisions.
+      class IdeaResolver
+        # @param root_dir [String] Root directory containing ideas
+        def initialize(root_dir)
+          @root_dir = root_dir
+          @scanner = IdeaScanner.new(root_dir)
+        end
+
+        # Resolve a reference to a scan result
+        # @param ref [String] Full ID (6 chars) or suffix shortcut (3 chars)
+        # @param warn_on_ambiguity [Boolean] Whether to print warning on ambiguity
+        # @return [ScanResult, nil] Resolved result or nil
+        def resolve(ref, warn_on_ambiguity: true)
+          scan_results = @scanner.scan
+          resolver = Ace::Support::Items::Molecules::ShortcutResolver.new(scan_results)
+
+          on_ambiguity = if warn_on_ambiguity
+            ->(matches) {
+              ids = matches.map(&:id).join(", ")
+              warn "Warning: Ambiguous shortcut '#{ref}' matches #{matches.size} ideas: #{ids}. Using most recent."
+            }
+          end
+
+          resolver.resolve(ref, on_ambiguity: on_ambiguity)
+        end
+
+        # Resolve with explicit ambiguity detection
+        # @param ref [String] Reference to resolve
+        # @return [Hash] Result with :result, :ambiguous, :matches keys
+        def resolve_with_info(ref)
+          scan_results = @scanner.scan
+          resolver = Ace::Support::Items::Molecules::ShortcutResolver.new(scan_results)
+
+          matches = resolver.all_matches(ref)
+
+          if matches.empty?
+            {result: nil, ambiguous: false, matches: []}
+          elsif matches.size == 1
+            {result: matches.first, ambiguous: false, matches: matches}
+          else
+            {result: matches.last, ambiguous: true, matches: matches}
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+require_relative "../atoms/idea_file_pattern"
+
+module Ace
+  module Idea
+    module Molecules
+      # Wraps DirectoryScanner for .idea.s.md files.
+      # Returns scan results with raw b36ts IDs (no type markers).
+      class IdeaScanner
+        attr_reader :last_scan_total, :last_folder_counts
+
+        # @param root_dir [String] Root directory containing ideas (e.g., ".ace-ideas")
+        def initialize(root_dir)
+          @root_dir = root_dir
+          @scanner = Ace::Support::Items::Molecules::DirectoryScanner.new(
+            root_dir,
+            file_pattern: Atoms::IdeaFilePattern::FILE_GLOB
+          )
+        end
+
+        # Scan for all ideas
+        # @return [Array<ScanResult>] Sorted scan results
+        def scan
+          @scanner.scan
+        end
+
+        # Scan and filter by special folder or virtual filter
+        # @param folder [String, nil] Folder name, virtual filter ("next", "all"), or nil for all
+        # @return [Array<ScanResult>] Filtered scan results
+        def scan_in_folder(folder)
+          results = scan
+          @last_scan_total = results.size
+          @last_folder_counts = results.group_by(&:special_folder).transform_values(&:size)
+          return results if folder.nil?
+
+          virtual = Ace::Support::Items::Atoms::SpecialFolderDetector.virtual_filter?(folder)
+          case virtual
+          when :all then results
+          when :next then results.select { |r| r.special_folder.nil? }
+          else
+            normalized = Ace::Support::Items::Atoms::SpecialFolderDetector.normalize(folder)
+            results.select { |r| r.special_folder == normalized }
+          end
+        end
+
+        # Check if root directory exists
+        # @return [Boolean]
+        def root_exists?
+          Dir.exist?(@root_dir)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/idea_file_pattern"
+require_relative "../atoms/idea_id_formatter"
+
+module Ace
+  module Idea
+    module Molecules
+      # Validates the directory structure of an ideas root directory.
+      # Checks folder naming, file naming, and structural conventions.
+      class IdeaStructureValidator
+        # @param root_dir [String] Root directory for ideas (e.g., ".ace-ideas")
+        def initialize(root_dir)
+          @root_dir = root_dir
+        end
+
+        # Validate the entire ideas directory structure
+        # @return [Array<Hash>] List of issues found
+        def validate(root_dir = @root_dir)
+          issues = []
+
+          unless Dir.exist?(root_dir)
+            issues << {type: :error, message: "Ideas root directory does not exist", location: root_dir}
+            return issues
+          end
+
+          check_folder_naming(root_dir, issues)
+          check_spec_files(root_dir, issues)
+          check_stale_backups(root_dir, issues)
+          check_empty_directories(root_dir, issues)
+
+          issues
+        end
+
+        private
+
+        # Check that idea folders follow {6-char-id}-{slug} naming
+        def check_folder_naming(root_dir, issues)
+          idea_dirs(root_dir).each do |dir|
+            folder_name = File.basename(dir)
+
+            # Skip special folders
+            next if folder_name.start_with?("_")
+
+            unless folder_name.match?(/^[0-9a-z]{6}-.+$/)
+              issues << {
+                type: :error,
+                message: "Folder name does not match '{id}-{slug}' convention: '#{folder_name}'",
+                location: dir
+              }
+            end
+          end
+        end
+
+        # Check that each idea folder has exactly one .idea.s.md spec file
+        def check_spec_files(root_dir, issues)
+          idea_dirs(root_dir).each do |dir|
+            folder_name = File.basename(dir)
+            next if folder_name.start_with?("_")
+
+            spec_files = Dir.glob(File.join(dir, Atoms::IdeaFilePattern::FILE_GLOB))
+
+            if spec_files.empty?
+              issues << {
+                type: :warning,
+                message: "No .idea.s.md spec file in idea folder",
+                location: dir
+              }
+            elsif spec_files.size > 1
+              issues << {
+                type: :warning,
+                message: "Multiple .idea.s.md spec files in folder (#{spec_files.size} found)",
+                location: dir
+              }
+            end
+          end
+        end
+
+        # Check for stale backup/tmp files
+        def check_stale_backups(root_dir, issues)
+          backup_patterns = [
+            File.join(root_dir, "**", "*.backup.*"),
+            File.join(root_dir, "**", "*.tmp"),
+            File.join(root_dir, "**", "*~")
+          ]
+
+          backup_patterns.each do |pattern|
+            Dir.glob(pattern).each do |file|
+              next if file.include?("/.git/")
+
+              issues << {
+                type: :warning,
+                message: "Stale backup file (safe to delete)",
+                location: file
+              }
+            end
+          end
+        end
+
+        # Check for empty directories
+        def check_empty_directories(root_dir, issues)
+          Dir.glob(File.join(root_dir, "**", "*")).each do |path|
+            next unless File.directory?(path)
+            next if path.include?("/.git/")
+
+            files = Dir.glob(File.join(path, "**", "*")).select { |f| File.file?(f) }
+            if files.empty?
+              issues << {
+                type: :warning,
+                message: "Empty directory (safe to delete)",
+                location: path
+              }
+            end
+          end
+        end
+
+        # Find all immediate subdirectories that look like idea folders
+        # (excludes special folders which are containers, includes their children)
+        # Also excludes category folders (folders containing only subdirectories)
+        def idea_dirs(root_dir)
+          dirs = []
+
+          # Direct children of root
+          Dir.glob(File.join(root_dir, "*")).each do |path|
+            next unless File.directory?(path)
+
+            folder_name = File.basename(path)
+            if folder_name.start_with?("_")
+              # Recurse into special folders
+              Dir.glob(File.join(path, "*")).each do |subpath|
+                dirs << subpath if File.directory?(subpath) && !category_folder?(subpath)
+              end
+            else
+              dirs << path unless category_folder?(path)
+            end
+          end
+
+          dirs
+        end
+
+        # Check if a folder is a category folder (only contains subdirectories, no files)
+        # These are organizational folders and not individual ideas
+        def category_folder?(dir_path)
+          return false unless Dir.exist?(dir_path)
+
+          # Check if folder has any files
+          files = Dir.glob(File.join(dir_path, "*")).select { |f| File.file?(f) }
+          return false if files.any?
+
+          # Check if folder has any subdirectories
+          subdirs = Dir.glob(File.join(dir_path, "*")).select { |f| File.directory?(f) }
+          subdirs.any?
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/organisms/idea_doctor.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/idea_scanner"
+require_relative "../molecules/idea_loader"
+require_relative "../molecules/idea_frontmatter_validator"
+require_relative "../molecules/idea_structure_validator"
+require_relative "../atoms/idea_validation_rules"
+
+module Ace
+  module Idea
+    module Organisms
+      # Orchestrates comprehensive health checks for the ideas system.
+      # Runs structure validation, frontmatter validation, and scope/status
+      # consistency checks across all ideas in a root directory.
+      class IdeaDoctor
+        attr_reader :root_path, :options
+
+        # @param root_path [String] Path to ideas root directory
+        # @param options [Hash] Diagnosis options (:check, :verbose, etc.)
+        def initialize(root_path, options = {})
+          @root_path = root_path
+          @options = options
+          @issues = []
+          @stats = {
+            ideas_scanned: 0,
+            folders_checked: 0,
+            errors: 0,
+            warnings: 0,
+            info: 0
+          }
+        end
+
+        # Run comprehensive health check
+        # @return [Hash] Diagnosis results
+        def run_diagnosis
+          unless @root_path && Dir.exist?(@root_path)
+            return {
+              valid: false,
+              health_score: 0,
+              issues: [{type: :error, message: "Ideas root directory not found: #{@root_path}"}],
+              stats: @stats,
+              duration: 0,
+              root_path: @root_path
+            }
+          end
+
+          @start_time = Time.now
+
+          if options[:check]
+            run_specific_check(options[:check])
+          else
+            run_full_check
+          end
+
+          health_score = calculate_health_score
+
+          {
+            valid: @stats[:errors] == 0,
+            health_score: health_score,
+            issues: @issues,
+            stats: @stats,
+            duration: Time.now - @start_time,
+            root_path: @root_path
+          }
+        end
+
+        # Check if an issue can be auto-fixed
+        # @param issue [Hash] Issue to check
+        # @return [Boolean]
+        def auto_fixable?(issue)
+          return false unless issue[:type] == :error || issue[:type] == :warning
+
+          Molecules::IdeaDoctorFixer::FIXABLE_PATTERNS.any? { |pattern| issue[:message].match?(pattern) }
+        end
+
+        private
+
+        def run_full_check
+          # 1. Structure checks (folder naming, file naming, backups, empty dirs)
+          run_structure_check
+
+          # 2. Frontmatter checks (per-file validation)
+          run_frontmatter_check
+
+          # 3. Scope/status consistency (cross-cutting)
+          run_scope_check
+        end
+
+        def run_specific_check(check_type)
+          case check_type.to_s
+          when "structure"
+            run_structure_check
+          when "frontmatter"
+            run_frontmatter_check
+          when "scope"
+            run_scope_check
+          else
+            add_issue(:error, "Unknown check type: #{check_type}")
+          end
+        end
+
+        def run_structure_check
+          validator = Molecules::IdeaStructureValidator.new(@root_path)
+          issues = validator.validate
+
+          issues.each do |issue|
+            add_issue(issue[:type], issue[:message], issue[:location])
+          end
+
+          # Count folders checked
+          @stats[:folders_checked] = count_idea_folders
+        end
+
+        def run_frontmatter_check
+          scanner = Molecules::IdeaScanner.new(@root_path)
+          return unless scanner.root_exists?
+
+          scan_results = scanner.scan
+          @stats[:ideas_scanned] = scan_results.size
+
+          scan_results.each do |scan_result|
+            spec_file = scan_result.file_path
+            next unless spec_file && File.exist?(spec_file)
+
+            issues = Molecules::IdeaFrontmatterValidator.validate(
+              spec_file,
+              special_folder: scan_result.special_folder
+            )
+
+            # Filter out scope issues here (handled separately in run_scope_check)
+            issues.reject! { |i| scope_issue?(i[:message]) }
+
+            issues.each do |issue|
+              add_issue(issue[:type], issue[:message], issue[:location])
+            end
+          end
+        end
+
+        def run_scope_check
+          scanner = Molecules::IdeaScanner.new(@root_path)
+          return unless scanner.root_exists?
+
+          scan_results = scanner.scan
+
+          scan_results.each do |scan_result|
+            spec_file = scan_result.file_path
+            next unless spec_file && File.exist?(spec_file)
+
+            # Load frontmatter for scope checking
+            content = File.read(spec_file)
+            frontmatter, _body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+            next unless frontmatter.is_a?(Hash)
+
+            status = frontmatter["status"]
+            special_folder = scan_result.special_folder
+
+            scope_issues = Atoms::IdeaValidationRules.scope_consistent?(status, special_folder)
+            scope_issues.each do |issue|
+              add_issue(issue[:type], issue[:message], spec_file)
+            end
+          end
+        end
+
+        def scope_issue?(message)
+          message.include?("not in _archive") ||
+            message.include?("in _archive/ but status") ||
+            message.include?("in _maybe/ with terminal")
+        end
+
+        def count_idea_folders
+          return 0 unless Dir.exist?(@root_path)
+
+          count = 0
+          Dir.glob(File.join(@root_path, "*")).each do |path|
+            next unless File.directory?(path)
+
+            count += if File.basename(path).start_with?("_")
+              Dir.glob(File.join(path, "*")).count { |p| File.directory?(p) }
+            else
+              1
+            end
+          end
+          count
+        end
+
+        def add_issue(type, message, location = nil)
+          issue = {type: type, message: message}
+          issue[:location] = location if location
+          @issues << issue
+
+          case type
+          when :error then @stats[:errors] += 1
+          when :warning then @stats[:warnings] += 1
+          when :info then @stats[:info] += 1
+          end
+        end
+
+        def calculate_health_score
+          score = 100
+          score -= @stats[:errors] * 10
+          score -= @stats[:warnings] * 2
+          [[score, 0].max, 100].min
+        end
+      end
+    end
+  end
+end