ace-assign 0.37.0

data/lib/ace/assign/atoms/composition_rules.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure functions for loading and applying composition rules.
+      #
+      # Composition rules define ordering constraints, step pairs,
+      # and conditional suggestions for building assignments.
+      #
+      # @example Validating ordering
+      #   rules = CompositionRules.load("/path/to/catalog")
+      #   violations = CompositionRules.validate_ordering(
+      #     ["work-on-task", "onboard"],
+      #     rules
+      #   )
+      #   # => [{ rule: "onboard-first", message: "onboard must be first" }]
+      module CompositionRules
+        # Load composition rules from catalog directory.
+        #
+        # @param catalog_dir [String] Path to catalog/ directory
+        # @return [Hash] Parsed rules with ordering, pairs, conditional, review_cycles
+        def self.load(catalog_dir)
+          rules_path = File.join(catalog_dir, "composition-rules.yml")
+          return default_rules unless File.exist?(rules_path)
+
+          YAML.safe_load_file(rules_path, permitted_classes: [Date]) || default_rules
+        rescue
+          default_rules
+        end
+
+        # Validate step ordering against rules.
+        #
+        # @param step_names [Array<String>] Ordered list of step names
+        # @param rules [Hash] Loaded composition rules
+        # @return [Array<Hash>] Violations, each with :rule and :message
+        def self.validate_ordering(step_names, rules)
+          violations = []
+          ordering_rules = rules["ordering"] || []
+
+          ordering_rules.each do |rule|
+            violation = check_ordering_rule(step_names, rule)
+            violations << violation if violation
+          end
+
+          violations
+        end
+
+        # Suggest additional steps based on the selected set and rules.
+        #
+        # @param step_names [Array<String>] Currently selected step names
+        # @param rules [Hash] Loaded composition rules
+        # @return [Array<Hash>] Suggestions, each with :step, :strength, :reason
+        def self.suggest_additions(step_names, rules)
+          suggestions = []
+
+          # Check pair completeness
+          (rules["pairs"] || []).each do |pair|
+            pair_suggestions = check_pair_completeness(step_names, pair)
+            suggestions.concat(pair_suggestions)
+          end
+
+          # Check conditional rules
+          (rules["conditional"] || []).each do |conditional|
+            conditional_suggestions = check_conditional_rule(step_names, conditional)
+            suggestions.concat(conditional_suggestions)
+          end
+
+          suggestions
+        end
+
+        # Default empty rules structure.
+        #
+        # @return [Hash] Empty rules
+        def self.default_rules
+          {
+            "ordering" => [],
+            "pairs" => [],
+            "conditional" => [],
+            "review_cycles" => {
+              "default_count" => 2,
+              "max_count" => 5
+            }
+          }
+        end
+        private_class_method :default_rules
+
+        # Check a single ordering rule against step sequence.
+        #
+        # Uses prefix matching so a rule referencing "release" matches
+        # steps named "release-minor" or "release-patch-1".
+        #
+        # @param step_names [Array<String>] Ordered list of step names
+        # @param rule [Hash] Ordering rule definition
+        # @return [Hash, nil] Violation hash or nil if rule is satisfied
+        def self.check_ordering_rule(step_names, rule)
+          # Position rules (e.g., "onboard must be first")
+          if rule["position"] == "first" && rule["step"]
+            step = rule["step"]
+            idx = find_step_index(step_names, step)
+            if idx && idx != 0
+              return {rule: rule["rule"], message: "'#{step}' must be first"}
+            end
+          end
+
+          # Before/after rules (e.g., "create-pr must come before review-pr")
+          if rule["before"] && rule["after"]
+            before_idx = find_step_index(step_names, rule["before"])
+            after_idx = find_step_index(step_names, rule["after"])
+
+            if before_idx && after_idx && before_idx >= after_idx
+              return {
+                rule: rule["rule"],
+                message: "'#{rule["before"]}' must come before '#{rule["after"]}'"
+              }
+            end
+          end
+
+          nil
+        end
+        private_class_method :check_ordering_rule
+
+        # Find the index of a step by exact name or prefix match.
+        #
+        # Allows rules to reference base names (e.g., "release") that match
+        # suffixed variants (e.g., "release-minor", "release-patch-1").
+        #
+        # Note: Rule names should be specific enough to avoid unintended matches.
+        # A short prefix like "re" would match both "release-minor" and
+        # "reorganize-commits". Use full base names in composition rules.
+        #
+        # @param step_names [Array<String>] Step name list
+        # @param name [String] Name to find (exact or prefix)
+        # @return [Integer, nil] Index or nil if not found
+        def self.find_step_index(step_names, name)
+          idx = step_names.index(name)
+          return idx if idx
+
+          step_names.index { |p| p.start_with?("#{name}-") }
+        end
+        private_class_method :find_step_index
+
+        # Check a conditional rule against the selected steps.
+        #
+        # Parses "assignment includes X or Y" patterns from the when field
+        # and checks if any referenced steps are present.
+        #
+        # @param step_names [Array<String>] Currently selected step names
+        # @param conditional [Hash] Conditional rule definition
+        # @return [Array<Hash>] Suggestions for steps to add
+        def self.check_conditional_rule(step_names, conditional)
+          suggestions = []
+          when_clause = conditional["when"] || ""
+          suggest_steps = conditional["suggest"] || []
+          strength = conditional["strength"] || "recommended"
+
+          # Parse "assignment includes X or/and Y" pattern.
+          # Supports "or" (any trigger) and "and" (all triggers) separately.
+          # Mixed conjunctions (e.g., "A or B and C") are not supported —
+          # "and" takes precedence when present.
+          if (match = when_clause.match(/assignment includes (.+)/i))
+            raw = match[1]
+            if raw.include?(" and ")
+              trigger_steps = raw.split(/\s+and\s+/).map(&:strip)
+              triggered = trigger_steps.all? { |p| step_names.include?(p) }
+            else
+              trigger_steps = raw.split(/\s+or\s+/).map(&:strip)
+              triggered = trigger_steps.any? { |p| step_names.include?(p) }
+            end
+
+            if triggered
+              suggest_steps.each do |step|
+                next if step_names.include?(step)
+
+                suggestions << {
+                  step: step,
+                  strength: strength,
+                  reason: when_clause
+                }
+              end
+            end
+          end
+
+          suggestions
+        end
+        private_class_method :check_conditional_rule
+
+        # Check if paired steps are complete.
+        #
+        # @param step_names [Array<String>] Currently selected step names
+        # @param pair [Hash] Pair definition
+        # @return [Array<Hash>] Suggestions for missing pair members
+        def self.check_pair_completeness(step_names, pair)
+          suggestions = []
+          pair_steps = pair["steps"] || []
+          return suggestions if pair_steps.length < 2
+          return suggestions if pair["pattern"] == "conditional"
+
+          present = pair_steps.select { |p| step_names.include?(p) }
+          return suggestions if present.empty? || present.length == pair_steps.length
+
+          missing = pair_steps - present
+          missing.each do |step|
+            suggestions << {
+              step: step,
+              strength: "recommended",
+              reason: "Part of '#{pair["name"]}' pair (#{pair["note"] || "paired steps"})"
+            }
+          end
+
+          suggestions
+        end
+        private_class_method :check_pair_completeness
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/number_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure functions for generating step numbers.
+      #
+      # Follows the numbering convention:
+      # - Main steps: 010, 020, 030 (10-step gaps for injection room)
+      # - Sub-steps: 010.01, 010.02 (2-digit padding)
+      # - Sub-sub-steps: 010.01.01 (3 levels max)
+      # - Dynamic injection: 041 after 040
+      module NumberGenerator
+        # Default increment between main steps
+        DEFAULT_INCREMENT = 10
+
+        # Default starting number
+        DEFAULT_START = 10
+
+        # Generate the next main step number
+        #
+        # @param last [String, nil] Last main step number (e.g., "040")
+        # @param increment [Integer] Step increment (default: 10)
+        # @return [String] Next main step number (e.g., "050")
+        def self.next_main(last, increment: DEFAULT_INCREMENT)
+          return format("%03d", DEFAULT_START) if last.nil?
+
+          # Extract the main number (before any dots)
+          main_part = last.split(".").first
+          current = main_part.to_i
+
+          # Round up to next increment
+          next_num = ((current / increment) + 1) * increment
+          format("%03d", next_num)
+        end
+
+        # Generate the next number after a given step (for dynamic injection)
+        #
+        # @param base [String] Base step number (e.g., "040")
+        # @param existing [Array<String>] Existing step numbers
+        # @return [String] Next available number (e.g., "041")
+        def self.next_after(base, existing = [])
+          # Extract main part
+          main_part = base.split(".").first.to_i
+
+          # Find existing numbers in the range base+1 to base+9
+          range_numbers = existing.map { |n| n.split(".").first.to_i }
+            .select { |n| n > main_part && n < main_part + 10 }
+
+          # Find next available
+          next_num = main_part + 1
+          while range_numbers.include?(next_num)
+            next_num += 1
+          end
+
+          format("%03d", next_num)
+        end
+
+        # Generate a sub-step number
+        #
+        # @param parent [String] Parent step number (e.g., "030")
+        # @param sequence [Integer] Sub-step sequence (1, 2, 3...)
+        # @return [String] Sub-step number (e.g., "030.01")
+        def self.subtask(parent, sequence)
+          "#{parent}.#{format("%02d", sequence)}"
+        end
+
+        # Generate a sub-sub-step number
+        #
+        # @param parent [String] Parent sub-step number (e.g., "030.01")
+        # @param sequence [Integer] Sub-sub-step sequence
+        # @return [String] Sub-sub-step number (e.g., "030.01.01")
+        def self.sub_subtask(parent, sequence)
+          "#{parent}.#{format("%02d", sequence)}"
+        end
+
+        # Parse a step number into its components
+        #
+        # @param number [String] Step number (e.g., "030.01.02")
+        # @return [Hash] Parsed components
+        def self.parse(number)
+          parts = number.split(".").map(&:to_i)
+          {
+            main: parts.first,
+            parts: parts,
+            depth: parts.size
+          }
+        end
+
+        # Check if a number is a sub-step of another
+        #
+        # @param number [String] Step number to check
+        # @param parent [String] Potential parent number
+        # @return [Boolean] True if number is a sub-step of parent
+        def self.subtask_of?(number, parent)
+          number.start_with?("#{parent}.")
+        end
+
+        # Format a number from index (0-based) to step number
+        #
+        # @param index [Integer] Zero-based index
+        # @param increment [Integer] Step increment
+        # @return [String] Step number
+        def self.from_index(index, increment: DEFAULT_INCREMENT)
+          format("%03d", (index + 1) * increment)
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/preset_expander.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure functions for expanding preset templates into step definitions.
+      #
+      # Handles `expansion:` directives in preset YAML files to generate
+      # hierarchical step structures from parameter arrays.
+      #
+      # Supports:
+      # - `batch-parent`: Creates a parent container step that auto-completes
+      # - `foreach`: Iterates over array parameter to create child steps
+      # - `child-template`: Template for generating foreach children
+      #
+      # @example Preset with expansion
+      #   expansion:
+      #     batch-parent:
+      #       name: batch-tasks
+      #       number: "010"
+      #       instructions: "Batch container - auto-completes when children done."
+      #     foreach: taskrefs
+      #     child-template:
+      #       name: "work-on-{{item}}"
+      #       parent: "010"
+      #       context: fork
+      #       instructions: "Implement task {{item}}"
+      #
+      # @example Generated steps for taskrefs: [148, 149, 150]
+      #   [
+      #     { number: "010", name: "batch-tasks", instructions: "..." },
+      #     { number: "010.01", name: "work-on-148", parent: "010", context: "fork", ... },
+      #     { number: "010.02", name: "work-on-149", parent: "010", context: "fork", ... },
+      #     { number: "010.03", name: "work-on-150", parent: "010", context: "fork", ... }
+      #   ]
+      module PresetExpander
+        # Expand a preset configuration into concrete steps.
+        #
+        # @param preset [Hash] Parsed preset YAML with optional expansion section
+        # @param parameters [Hash] Parameter values including arrays for foreach
+        # @return [Array<Hash>] Expanded steps ready for job.yaml
+        def self.expand(preset, parameters = {})
+          parameters = normalize_taskref_alias(parameters)
+          expansion = preset["expansion"]
+          base_steps = preset["steps"] || []
+
+          # If no expansion section, return base steps with parameter substitution
+          unless expansion
+            return base_steps.map { |step| substitute_parameters(step, parameters) }
+          end
+
+          expanded_steps = []
+
+          # Process batch-parent if present
+          if expansion["batch-parent"]
+            parent_step = build_batch_parent(expansion["batch-parent"], parameters)
+            expanded_steps << parent_step
+          end
+
+          # Process foreach expansion if present
+          if expansion["foreach"] && expansion["child-template"]
+            foreach_param = expansion["foreach"]
+            items = normalize_array_parameter(parameters[foreach_param])
+
+            unless items.empty?
+              child_steps = build_foreach_children(
+                expansion["child-template"],
+                items,
+                parameters
+              )
+              expanded_steps.concat(child_steps)
+            end
+          end
+
+          # Add remaining base steps with parameter substitution
+          base_steps.each do |step|
+            expanded_step = substitute_parameters(step, parameters)
+            expanded_steps << expanded_step
+          end
+
+          expanded_steps
+        end
+
+        # Parse array parameter from various input formats.
+        #
+        # @param value [String, Array, nil] Parameter value
+        # @return [Array<String>] Normalized array of values
+        def self.parse_array_parameter(value)
+          return [] if value.nil?
+          return value.map(&:to_s) if value.is_a?(Array)
+
+          value_str = value.to_s.strip
+          return [] if value_str.empty?
+
+          # Check for range pattern (e.g., "148-152")
+          if value_str.match?(/^\d+-\d+$/)
+            start_num, end_num = value_str.split("-").map(&:to_i)
+            return (start_num..end_num).map(&:to_s)
+          end
+
+          # Check for comma-separated values
+          if value_str.include?(",")
+            return value_str.split(",").map(&:strip)
+          end
+
+          # Check for pattern (contains * or ?)
+          if value_str.match?(/[*?]/)
+            # Return pattern as single-element array for later resolution
+            return [value_str]
+          end
+
+          # Single value
+          [value_str]
+        end
+
+        # Validate preset parameters against requirements.
+        #
+        # @param preset [Hash] Preset configuration
+        # @param parameters [Hash] Provided parameter values
+        # @return [Array<String>] List of validation errors (empty if valid)
+        def self.validate_parameters(preset, parameters)
+          parameters = normalize_taskref_alias(parameters)
+          errors = []
+          param_defs = preset["parameters"] || {}
+
+          param_defs.each do |name, config|
+            next unless config["required"]
+
+            value = parameters[name]
+            if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+              errors << "Required parameter '#{name}' is missing"
+            end
+          end
+
+          errors
+        end
+
+        # Check if a preset has expansion directives.
+        #
+        # @param preset [Hash] Preset configuration
+        # @return [Boolean] True if preset uses expansion
+        def self.has_expansion?(preset)
+          !preset["expansion"].nil?
+        end
+
+        # Get the foreach parameter name from preset expansion.
+        #
+        # @param preset [Hash] Preset configuration
+        # @return [String, nil] Name of the foreach parameter
+        def self.foreach_parameter(preset)
+          preset.dig("expansion", "foreach")
+        end
+
+        private
+
+        # Normalize array parameter value.
+        #
+        # @param value [Object] Raw parameter value
+        # @return [Array<String>] Normalized array
+        def self.normalize_array_parameter(value)
+          parse_array_parameter(value)
+        end
+        private_class_method :normalize_array_parameter
+
+        # Normalize single-task shorthand onto batch parameter name.
+        #
+        # Canonical batch presets now use taskrefs; callers may still pass
+        # taskref for single-task usage.
+        def self.normalize_taskref_alias(parameters)
+          params = (parameters || {}).dup
+          return params unless params["taskrefs"].nil? || params["taskrefs"] == ""
+
+          taskref = params["taskref"]
+          return params if taskref.nil? || taskref.to_s.strip.empty?
+
+          params["taskrefs"] = [taskref.to_s]
+          params
+        end
+        private_class_method :normalize_taskref_alias
+
+        # Build the batch parent step.
+        #
+        # @param config [Hash] batch-parent configuration
+        # @param parameters [Hash] Parameter values for substitution
+        # @return [Hash] Parent step definition
+        def self.build_batch_parent(config, parameters)
+          step = {
+            "number" => config["number"] || "010",
+            "name" => substitute_string(config["name"] || "batch-tasks", parameters),
+            "instructions" => substitute_string(config["instructions"] || "", parameters)
+          }
+
+          step["skill"] = config["skill"] if config["skill"]
+          step["context"] = config["context"] if config["context"]
+
+          step
+        end
+        private_class_method :build_batch_parent
+
+        # Build child steps from foreach template.
+        #
+        # @param template [Hash] child-template configuration
+        # @param items [Array<String>] Items to iterate over
+        # @param parameters [Hash] Additional parameter values
+        # @return [Array<Hash>] Generated child steps
+        def self.build_foreach_children(template, items, parameters)
+          parent_number = template["parent"] || "010"
+          steps = []
+
+          items.each_with_index do |item, index|
+            # Build child number: parent.01, parent.02, etc.
+            child_number = "#{parent_number}.#{format("%02d", index + 1)}"
+
+            # Create merged parameters with {{item}} available
+            item_params = parameters.merge("item" => item)
+            raw_step = template.dup
+            raw_step["number"] = child_number
+            raw_step["parent"] = parent_number
+            raw_step["name"] ||= "item-#{item}"
+            raw_step["instructions"] ||= ""
+            step = substitute_parameters(raw_step, item_params)
+
+            steps << step
+          end
+
+          steps
+        end
+        private_class_method :build_foreach_children
+
+        # Substitute parameters in a step definition.
+        #
+        # @param step [Hash] Step configuration
+        # @param parameters [Hash] Parameter values
+        # @return [Hash] Step with substituted values
+        def self.substitute_parameters(step, parameters)
+          substitute_value(step, parameters)
+        end
+        private_class_method :substitute_parameters
+
+        def self.substitute_value(value, parameters)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), result|
+              result[key] = substitute_value(nested, parameters)
+            end
+          when Array
+            value.map { |item| substitute_value(item, parameters) }
+          when String
+            substitute_string(value, parameters)
+          else
+            value
+          end
+        end
+        private_class_method :substitute_value
+
+        # Substitute {{placeholder}} tokens in a string.
+        #
+        # @param text [String, nil] Text with placeholders
+        # @param parameters [Hash] Parameter values
+        # @return [String] Text with substituted values
+        def self.substitute_string(text, parameters)
+          return "" if text.nil?
+          return text unless text.is_a?(String)
+
+          result = text.dup
+          parameters.each do |key, value|
+            # Handle array values by joining with comma
+            display_value = value.is_a?(Array) ? value.join(", ") : value.to_s
+            result = result.gsub("{{#{key}}}", display_value)
+          end
+          result
+        end
+        private_class_method :substitute_string
+      end
+    end
+  end
+end