ace-retro 0.16.0

data/lib/ace/retro/molecules/retro_structure_validator.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/retro_file_pattern"
+require_relative "../atoms/retro_id_formatter"
+
+module Ace
+  module Retro
+    module Molecules
+      # Validates the directory structure of a retros root directory.
+      # Checks folder naming, file naming, and structural conventions.
+      class RetroStructureValidator
+        # @param root_dir [String] Root directory for retros (e.g., ".ace-retros")
+        def initialize(root_dir)
+          @root_dir = root_dir
+        end
+
+        # Validate the entire retros 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: "Retros root directory does not exist", location: root_dir}
+            return issues
+          end
+
+          check_folder_naming(root_dir, issues)
+          check_retro_files(root_dir, issues)
+          check_archive_partitions(root_dir, issues)
+          check_stale_backups(root_dir, issues)
+          check_empty_directories(root_dir, issues)
+
+          issues
+        end
+
+        private
+
+        # Check that retro folders follow {6-char-id}-{slug} naming
+        def check_folder_naming(root_dir, issues)
+          retro_dirs(root_dir).each do |dir|
+            folder_name = File.basename(dir)
+            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 retro folder has exactly one .retro.md file
+        def check_retro_files(root_dir, issues)
+          retro_dirs(root_dir).each do |dir|
+            folder_name = File.basename(dir)
+            next if folder_name.start_with?("_")
+
+            retro_files = Dir.glob(File.join(dir, Atoms::RetroFilePattern::FILE_GLOB))
+
+            if retro_files.empty?
+              issues << {
+                type: :warning,
+                message: "No .retro.md file in retro folder",
+                location: dir
+              }
+            elsif retro_files.size > 1
+              issues << {
+                type: :warning,
+                message: "Multiple .retro.md files in folder (#{retro_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
+
+        # Check that _archive/ partition directories use valid b36ts names
+        def check_archive_partitions(root_dir, issues)
+          archive_dir = File.join(root_dir, "_archive")
+          return unless Dir.exist?(archive_dir)
+
+          Dir.glob(File.join(archive_dir, "*")).each do |path|
+            next unless File.directory?(path)
+            next unless category_folder?(path)
+
+            partition_name = File.basename(path)
+            unless valid_b36ts_partition?(partition_name)
+              issues << {
+                type: :error,
+                message: "Invalid archive partition '#{partition_name}' (expected b36ts like '8o')",
+                location: path
+              }
+            end
+          end
+        end
+
+        # Valid b36ts month partitions are 1-3 char lowercase base36 strings
+        def valid_b36ts_partition?(name)
+          name.match?(/\A[0-9a-z]{1,3}\z/)
+        end
+
+        # Find all immediate subdirectories that look like retro folders
+        # (excludes special folders which are containers, includes their children)
+        # Also excludes category folders (folders containing only subdirectories)
+        # For _archive/, recurses into partition dirs (category folders) to find retros inside them
+        def retro_dirs(root_dir)
+          dirs = []
+
+          Dir.glob(File.join(root_dir, "*")).each do |path|
+            next unless File.directory?(path)
+
+            folder_name = File.basename(path)
+            if folder_name == "_archive"
+              Dir.glob(File.join(path, "*")).each do |subpath|
+                next unless File.directory?(subpath)
+
+                if category_folder?(subpath)
+                  # Partition dir — recurse into it to find retro folders
+                  Dir.glob(File.join(subpath, "*")).each do |retro_path|
+                    dirs << retro_path if File.directory?(retro_path)
+                  end
+                else
+                  dirs << subpath
+                end
+              end
+            elsif folder_name.start_with?("_")
+              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 retros
+        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/retro/organisms/retro_doctor.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/retro_scanner"
+require_relative "../molecules/retro_loader"
+require_relative "../molecules/retro_frontmatter_validator"
+require_relative "../molecules/retro_structure_validator"
+require_relative "../atoms/retro_validation_rules"
+
+module Ace
+  module Retro
+    module Organisms
+      # Orchestrates comprehensive health checks for the retros system.
+      # Runs structure validation, frontmatter validation, and scope/status
+      # consistency checks across all retros in a root directory.
+      class RetroDoctor
+        attr_reader :root_path, :options
+
+        # @param root_path [String] Path to retros root directory
+        # @param options [Hash] Diagnosis options (:check, :verbose, etc.)
+        def initialize(root_path, options = {})
+          @root_path = root_path
+          @options = options
+          @issues = []
+          @stats = {
+            retros_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: "Retros 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::RetroDoctorFixer::FIXABLE_PATTERNS.any? { |pattern| issue[:message].match?(pattern) }
+        end
+
+        private
+
+        def run_full_check
+          run_structure_check
+          run_frontmatter_check
+          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::RetroStructureValidator.new(@root_path)
+          issues = validator.validate
+
+          issues.each do |issue|
+            add_issue(issue[:type], issue[:message], issue[:location])
+          end
+
+          @stats[:folders_checked] = count_retro_folders
+        end
+
+        def run_frontmatter_check
+          scanner = Molecules::RetroScanner.new(@root_path)
+          return unless scanner.root_exists?
+
+          scan_results = scanner.scan
+          @stats[:retros_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::RetroFrontmatterValidator.validate(
+              spec_file,
+              special_folder: scan_result.special_folder
+            )
+
+            # Filter out scope issues (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::RetroScanner.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)
+
+            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::RetroValidationRules.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")
+        end
+
+        def count_retro_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

data/lib/ace/retro/organisms/retro_manager.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../atoms/retro_frontmatter_defaults"
+require_relative "../molecules/retro_config_loader"
+require_relative "../molecules/retro_scanner"
+require_relative "../molecules/retro_resolver"
+require_relative "../molecules/retro_loader"
+require_relative "../molecules/retro_creator"
+require_relative "../molecules/retro_mover"
+
+module Ace
+  module Retro
+    module Organisms
+      # Orchestrates all retro CRUD operations.
+      # Entry point for retro management with config-driven root directory.
+      class RetroManager
+        attr_reader :last_list_total, :last_folder_counts
+
+        # @param root_dir [String, nil] Override root directory for retros
+        # @param config [Hash, nil] Override configuration
+        def initialize(root_dir: nil, config: nil)
+          @config = config || load_config
+          @root_dir = root_dir || resolve_root_dir
+        end
+
+        # Create a new retro
+        # @param title [String] Retro title
+        # @param type [String, nil] Retro type (standard, conversation-analysis, self-review)
+        # @param tags [Array<String>] Tags
+        # @param move_to [String, nil] Target folder
+        # @return [Retro] Created retro
+        def create(title, type: nil, tags: [], move_to: nil)
+          ensure_root_dir
+          creator = Molecules::RetroCreator.new(root_dir: @root_dir, config: @config)
+          creator.create(title, type: type, tags: tags, move_to: move_to)
+        end
+
+        # Show (load) a single retro by reference
+        # @param ref [String] Full ID (6 chars) or suffix shortcut (3 chars)
+        # @return [Retro, nil] Loaded retro or nil if not found
+        def show(ref)
+          resolver = Molecules::RetroResolver.new(@root_dir)
+          scan_result = resolver.resolve(ref)
+          return nil unless scan_result
+
+          loader = Molecules::RetroLoader.new
+          loader.load(scan_result.dir_path,
+            id: scan_result.id,
+            special_folder: scan_result.special_folder)
+        end
+
+        # List retros with optional filtering
+        # @param status [String, nil] Filter by status
+        # @param type [String, nil] Filter by type
+        # @param in_folder [String, nil] Filter by special folder (default: "next" = root items only)
+        # @param tags [Array<String>] Filter by tags (any match)
+        # @return [Array<Retro>] List of retros
+        def list(status: nil, type: nil, in_folder: "next", tags: [])
+          scanner = Molecules::RetroScanner.new(@root_dir)
+          scan_results = scanner.scan_in_folder(in_folder)
+          @last_list_total = scanner.last_scan_total
+          @last_folder_counts = scanner.last_folder_counts
+
+          loader = Molecules::RetroLoader.new
+          retros = scan_results.filter_map do |sr|
+            loader.load(sr.dir_path, id: sr.id, special_folder: sr.special_folder)
+          end
+
+          retros = retros.select { |r| r.status == status } if status
+          retros = retros.select { |r| r.type == type } if type
+          retros = filter_by_tags(retros, tags) if tags.any?
+
+          retros
+        end
+
+        # Update a retro's fields and optionally move to a folder.
+        # @param ref [String] Retro reference
+        # @param set [Hash] Fields to set (key => value)
+        # @param add [Hash] Fields to add to (for arrays like tags)
+        # @param remove [Hash] Fields to remove from (for arrays)
+        # @param move_to [String, nil] Target folder to move to (archive, maybe, next/root//)
+        # @return [Retro, nil] Updated retro or nil if not found
+        def update(ref, set: {}, add: {}, remove: {}, move_to: nil)
+          scan_result = resolve_scan_result(ref)
+          return nil unless scan_result
+
+          loader = Molecules::RetroLoader.new
+          retro = loader.load(scan_result.dir_path,
+            id: scan_result.id,
+            special_folder: scan_result.special_folder)
+          return nil unless retro
+
+          # Apply field updates if any
+          has_field_updates = [set, add, remove].any? { |h| h && !h.empty? }
+          update_retro_file(retro, set: set, add: add, remove: remove) if has_field_updates
+
+          # Apply move if requested
+          current_path = retro.path
+          current_special = retro.special_folder
+          if move_to
+            mover = Molecules::RetroMover.new(@root_dir)
+            new_path = if Ace::Support::Items::Atoms::SpecialFolderDetector.move_to_root?(move_to)
+              mover.move_to_root(retro)
+            else
+              archive_date = parse_archive_date(retro)
+              mover.move(retro, to: move_to, date: archive_date)
+            end
+            current_path = new_path
+            current_special = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
+              new_path, root: @root_dir
+            )
+          end
+
+          # Reload and return updated retro
+          loader.load(current_path, id: retro.id, special_folder: current_special)
+        end
+
+        # Get the root directory
+        # @return [String] Absolute path to retros root
+        attr_reader :root_dir
+
+        private
+
+        def load_config
+          gem_root = File.expand_path("../../../..", __dir__)
+          # lib/ace/retro/organisms/ → 4 levels up to gem root
+          Molecules::RetroConfigLoader.load(gem_root: gem_root)
+        end
+
+        def resolve_root_dir
+          Molecules::RetroConfigLoader.root_dir(@config)
+        end
+
+        def ensure_root_dir
+          require "fileutils"
+          FileUtils.mkdir_p(@root_dir) unless Dir.exist?(@root_dir)
+        end
+
+        def resolve_scan_result(ref)
+          resolver = Molecules::RetroResolver.new(@root_dir)
+          resolver.resolve(ref)
+        end
+
+        def filter_by_tags(retros, tags)
+          return retros if tags.empty?
+
+          retros.select do |retro|
+            tags.any? { |tag| retro.tags.include?(tag) }
+          end
+        end
+
+        def update_retro_file(retro, set:, add:, remove:)
+          content = File.read(retro.file_path)
+          frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+          # Strip leading newline from body so rebuild doesn't double-space
+          body = body.sub(/\A\n/, "")
+
+          # Apply set operations
+          set.each { |k, v| frontmatter[k.to_s] = v }
+
+          # Apply add operations (for arrays)
+          add.each do |k, v|
+            key = k.to_s
+            current = Array(frontmatter[key])
+            values = Array(v)
+            frontmatter[key] = (current + values).uniq
+          end
+
+          # Apply remove operations (for arrays)
+          remove.each do |k, v|
+            key = k.to_s
+            next unless frontmatter[key].is_a?(Array)
+
+            values = Array(v)
+            frontmatter[key] = frontmatter[key] - values
+          end
+
+          # Write back atomically (temp + rename to avoid partial writes)
+          new_content = Ace::Support::Items::Atoms::FrontmatterSerializer.rebuild(frontmatter, body)
+          tmp_path = "#{retro.file_path}.tmp.#{Process.pid}"
+          File.write(tmp_path, new_content)
+          File.rename(tmp_path, retro.file_path)
+        ensure
+          begin
+            File.unlink(tmp_path) if tmp_path && File.exist?(tmp_path)
+          rescue
+            nil
+          end
+        end
+
+        # Extract archive date from retro frontmatter, falling back to Time.now
+        def parse_archive_date(retro)
+          raw = retro.metadata["completed_at"] || retro.created_at
+          return nil unless raw
+
+          case raw
+          when Time then raw
+          when DateTime then raw.to_time
+          else begin
+            Time.parse(raw.to_s)
+          rescue
+            nil
+          end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ace
+  module Retro
+    VERSION = "0.16.0"
+  end
+end

data/lib/ace/retro.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "retro/version"
+
+# External dependencies
+require "ace/b36ts"
+require "ace/support/items"
+
+# Atoms
+require_relative "retro/atoms/retro_id_formatter"
+require_relative "retro/atoms/retro_file_pattern"
+require_relative "retro/atoms/retro_frontmatter_defaults"
+require_relative "retro/atoms/retro_validation_rules"
+
+# Models
+require_relative "retro/models/retro"
+
+# Molecules
+require_relative "retro/molecules/retro_config_loader"
+require_relative "retro/molecules/retro_scanner"
+require_relative "retro/molecules/retro_resolver"
+require_relative "retro/molecules/retro_loader"
+require_relative "retro/molecules/retro_creator"
+require_relative "retro/molecules/retro_mover"
+require_relative "retro/molecules/retro_display_formatter"
+require_relative "retro/molecules/retro_frontmatter_validator"
+require_relative "retro/molecules/retro_structure_validator"
+require_relative "retro/molecules/retro_doctor_fixer"
+require_relative "retro/molecules/retro_doctor_reporter"
+
+# Organisms
+require_relative "retro/organisms/retro_manager"
+require_relative "retro/organisms/retro_doctor"
+
+module Ace
+  # Retro management gem for ACE.
+  # Manages retrospectives in .ace-retros/ using raw 6-char b36ts IDs.
+  module Retro
+    class Error < StandardError; end
+  end
+end