rosett-ai 1.3.3

data/lib/rosett_ai/composition/composer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Composition
+    # Orchestrates behaviour composition: discovers behaviour files,
+    # resolves scopes, sorts by priority, detects conflicts and
+    # circular dependencies, and produces a deterministic result.
+    #
+    # Supports configurable merge strategies for rule ID collisions:
+    # - first_wins: highest-priority rule wins (default)
+    # - deep_merge: recursively merge hash fields from all scopes
+    # - array_union: combine array fields from all scopes
+    #
+    # @author hugo
+    # @author claude
+    class Composer
+      # @param scope_resolver [ScopeResolver] scope resolution strategy
+      # @param priority_sorter [PrioritySorter] priority sorting strategy
+      # @param conflict_detector [ConflictDetector] conflict detection
+      # @param cycle_detector [CircularDependencyDetector] cycle detection
+      def initialize(
+        scope_resolver: ScopeResolver.new,
+        priority_sorter: PrioritySorter.new,
+        conflict_detector: ConflictDetector.new,
+        cycle_detector: CircularDependencyDetector.new
+      )
+        @scope_resolver = scope_resolver
+        @priority_sorter = priority_sorter
+        @conflict_detector = conflict_detector
+        @cycle_detector = cycle_detector
+      end
+
+      # Composes all behaviour files into a single result.
+      #
+      # @param behaviour_files [Array<String>] paths to behaviour YAML files
+      # @param project_root [Pathname, nil] project root for scope resolution
+      # @param strict [Boolean] treat warnings as errors
+      # @param target [String, nil] compilation target (for sensitive filtering)
+      # @param merge_strategy [String] merge strategy name (first_wins, deep_merge, array_union)
+      # @return [CompositionResult]
+      # @raise [RosettAi::CompositionError] on circular dependencies or strict conflicts
+      def compose(behaviour_files, project_root: nil, strict: false, target: nil,
+                  merge_strategy: 'first_wins')
+        behaviours = load_behaviours(behaviour_files, project_root: project_root)
+        check_circular_dependencies!(behaviours)
+
+        annotated_rules = annotate_rules(behaviours)
+        annotated_rules = filter_sensitive(annotated_rules, target) if target
+
+        sorted_rules = @priority_sorter.sort_rules(annotated_rules)
+        conflicts = @conflict_detector.detect(sorted_rules)
+
+        if strict && !conflicts.empty?
+          raise RosettAi::CompositionError,
+                "Composition conflicts in strict mode:\n#{conflicts.join("\n")}"
+        end
+
+        strategy = MergeStrategy.resolve(merge_strategy)
+        merged_rules = strategy.new.apply(sorted_rules)
+
+        trace = build_trace(merged_rules)
+        warnings = build_warnings(conflicts, behaviours)
+        sources = behaviours.to_h { |behaviour| [behaviour[:name], behaviour[:scope]] }
+
+        CompositionResult.new(
+          rules: merged_rules,
+          trace: trace,
+          warnings: warnings,
+          conflicts: conflicts,
+          sources: sources,
+          merge_strategy: merge_strategy
+        )
+      end
+
+      private
+
+      def load_behaviours(files, project_root:)
+        files.map do |file|
+          data = RosettAi::YamlLoader.load_file(file)
+          scope = @scope_resolver.resolve(file, project_root: project_root)
+          {
+            name: data['name'],
+            path: file,
+            scope: scope,
+            scope_weight: @scope_resolver.weight(scope),
+            domain: data.fetch('domain', nil),
+            sensitive: data.fetch('sensitive', false),
+            depends_on: Array(data['depends_on']),
+            rules: Array(data['rules'])
+          }
+        end
+      end
+
+      def check_circular_dependencies!(behaviours)
+        graph = behaviours.to_h { |behaviour| [behaviour[:name], behaviour[:depends_on]] }
+        cycle = @cycle_detector.detect(graph)
+
+        return unless cycle
+
+        raise RosettAi::CompositionError,
+              "Circular dependency detected: #{cycle.join(' -> ')}"
+      end
+
+      def annotate_rules(behaviours)
+        behaviours.flat_map do |behaviour|
+          behaviour[:rules].map do |rule|
+            {
+              id: rule['id'],
+              description: rule['description'],
+              priority: rule.fetch('priority', 50),
+              enabled: rule.fetch('enabled', true),
+              behaviour_name: behaviour[:name],
+              scope: behaviour[:scope],
+              scope_weight: behaviour[:scope_weight],
+              domain: behaviour[:domain],
+              sensitive: behaviour[:sensitive]
+            }
+          end
+        end
+      end
+
+      def filter_sensitive(rules, target)
+        return rules if target == 'claude' || target.nil?
+
+        rules.reject { |r| r[:sensitive] }
+      end
+
+      def build_trace(sorted_rules)
+        sorted_rules.each_with_index.map do |rule, index|
+          {
+            position: index + 1,
+            rule_id: rule[:id],
+            behaviour: rule[:behaviour_name],
+            scope: rule[:scope],
+            priority: rule[:priority]
+          }
+        end
+      end
+
+      def build_warnings(conflicts, behaviours)
+        warnings = conflicts.dup
+
+        behaviours.each do |behaviour|
+          ids = behaviour[:rules].map { |r| r['id'] }
+          duplicates = ids.select { |id| ids.count(id) > 1 }.uniq
+          duplicates.each do |dup_id|
+            warnings << "Duplicate rule ID #{dup_id} within #{behaviour[:name]}.yml"
+          end
+        end
+
+        warnings
+      end
+    end
+  end
+end

data/lib/rosett_ai/composition/composition_result.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Composition
+    # Value object representing the final result of behaviour composition.
+    # Contains the merged rules, metadata about how they were composed,
+    # and any warnings or conflicts detected during composition.
+    class CompositionResult
+      # @return [Array<Hash>] final merged rules in priority order
+      attr_reader :rules
+
+      # @return [Array<Hash>] trace entries showing composition decisions
+      attr_reader :trace
+
+      # @return [Array<String>] warnings emitted during composition
+      attr_reader :warnings
+
+      # @return [Array<String>] conflicts detected (rule ID collisions)
+      attr_reader :conflicts
+
+      # @return [Hash{String => String}] behaviour name => scope mapping
+      attr_reader :sources
+
+      # @return [String] merge strategy used during composition
+      attr_reader :merge_strategy
+
+      # @param rules [Array<Hash>] composed rules
+      # @param trace [Array<Hash>] composition trace entries
+      # @param warnings [Array<String>] composition warnings
+      # @param conflicts [Array<String>] detected conflicts
+      # @param sources [Hash{String => String}] behaviour source mapping
+      # @param merge_strategy [String] merge strategy name
+      # rubocop:disable Metrics/ParameterLists -- value object with all-keyword defaults
+      def initialize(rules:, trace: [], warnings: [], conflicts: [], sources: {},
+                     merge_strategy: 'first_wins')
+        # rubocop:enable Metrics/ParameterLists
+        @rules = rules.freeze
+        @trace = trace.freeze
+        @warnings = warnings.freeze
+        @conflicts = conflicts.freeze
+        @sources = sources.freeze
+        @merge_strategy = merge_strategy.freeze
+      end
+
+      # @return [Integer] total number of composed rules
+      def rule_count
+        rules.size
+      end
+
+      # @return [Boolean] true if any conflicts were detected
+      def conflicts?
+        !conflicts.empty?
+      end
+
+      # @return [Boolean] true if any warnings were emitted
+      def warnings?
+        !warnings.empty?
+      end
+    end
+  end
+end

data/lib/rosett_ai/composition/conflict_detector.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Composition
+    # Detects rule ID collisions across behaviour files.
+    # When two behaviours define the same rule ID at the same scope
+    # and priority, this is a conflict that must be reported.
+    class ConflictDetector
+      # Detects rule ID collisions in a list of annotated rules.
+      #
+      # @param rules [Array<Hash>] rules with :id, :behaviour_name, :scope, :priority
+      # @return [Array<String>] conflict descriptions
+      def detect(rules)
+        conflicts = []
+        seen = {}
+
+        rules.each do |rule|
+          rule_id = rule[:id]
+          key = rule_id.to_s
+
+          if seen.key?(key)
+            existing = seen[key]
+            conflicts << format_conflict(rule_id, existing, rule)
+          else
+            seen[key] = rule
+          end
+        end
+
+        conflicts
+      end
+
+      # Checks if a security-domain rule would be overridden by a
+      # non-security rule. This is never allowed.
+      #
+      # @param existing [Hash] the existing rule
+      # @param candidate [Hash] the candidate replacement
+      # @return [Boolean] true if this is an invalid override
+      def security_override?(existing, candidate)
+        existing[:domain] == 'security' && candidate[:domain] != 'security'
+      end
+
+      private
+
+      def format_conflict(rule_id, existing, candidate)
+        "Rule ID collision: #{rule_id} defined in both " \
+          "#{existing[:behaviour_name]}.yml and #{candidate[:behaviour_name]}.yml"
+      end
+    end
+  end
+end

data/lib/rosett_ai/composition/lockfile.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'digest'
+require 'yaml'
+
+module RosettAi
+  module Composition
+    # Manages the `.rosett-ai-lock.yml` lockfile for reproducible behaviour
+    # composition. Writes the exact composition result so that
+    # `--frozen` compilations can reproduce the same output.
+    class Lockfile
+      FILENAME = '.rosett-ai-lock.yml'
+
+      # @param root [Pathname] project root directory
+      def initialize(root:)
+        @root = Pathname.new(root)
+      end
+
+      # @return [Pathname] full path to the lockfile
+      def path
+        @root.join(FILENAME)
+      end
+
+      # @return [Boolean] true if the lockfile exists
+      def exist?
+        path.exist?
+      end
+
+      # Writes the lockfile from a CompositionResult.
+      #
+      # @param result [CompositionResult] composition result
+      # @param behaviours [Array<Hash>] source behaviour metadata
+      # @return [Pathname] path to the written lockfile
+      def write(result, behaviours:)
+        data = build_lockfile_data(result, behaviours)
+        path.write(YAML.dump(data))
+        path
+      end
+
+      # Reads and parses the lockfile.
+      #
+      # @return [Hash] lockfile data
+      # @raise [RosettAi::CompositionError] if lockfile is missing or invalid
+      def read
+        raise RosettAi::CompositionError, "Lockfile not found: #{path}" unless exist?
+
+        RosettAi::YamlLoader.load_file(path.to_s)
+      end
+
+      # Checks if behaviour files have changed since the lockfile was written.
+      #
+      # @param behaviour_files [Array<String>] current behaviour file paths
+      # @return [Boolean] true if files match the lockfile
+      def fresh?(behaviour_files)
+        return false unless exist?
+
+        data = read
+        locked_checksums = data.fetch('behaviours', {})
+        current_checksums = compute_checksums(behaviour_files)
+
+        locked_checksums == current_checksums
+      end
+
+      private
+
+      def build_lockfile_data(result, behaviours)
+        {
+          'lockfile_version' => 1,
+          'generated_at' => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ'),
+          'generator' => 'rosett-ai',
+          'generator_version' => RosettAi::VERSION,
+          'merge_strategy' => result.merge_strategy,
+          'rule_count' => result.rule_count,
+          'behaviours' => compute_checksums(behaviours.filter_map { |entry| entry[:path] }),
+          'composition' => result.rules.map do |rule|
+            {
+              'id' => rule[:id],
+              'behaviour' => rule[:behaviour_name],
+              'scope' => rule[:scope],
+              'priority' => rule[:priority]
+            }
+          end
+        }
+      end
+
+      def compute_checksums(file_paths)
+        file_paths.sort.to_h do |fp|
+          content = File.read(fp, encoding: 'utf-8')
+          [relative_path(fp), "sha256:#{Digest::SHA256.hexdigest(content)}"]
+        end
+      end
+
+      def relative_path(file_path)
+        Pathname.new(file_path).relative_path_from(@root).to_s
+      rescue ArgumentError
+        file_path.to_s
+      end
+    end
+  end
+end

data/lib/rosett_ai/composition/merge_strategy.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Composition
+    # Configurable merge strategies for resolving rule ID collisions across
+    # scopes. When the same rule ID exists in multiple behaviours, the merge
+    # strategy determines which value(s) appear in the final composition.
+    #
+    # @author hugo
+    # @author claude
+    module MergeStrategy
+      STRATEGIES = ['first_wins', 'deep_merge', 'array_union'].freeze
+
+      # Resolves the strategy class from a name string.
+      #
+      # @param name [String] strategy name (first_wins, deep_merge, array_union)
+      # @return [Class] strategy class
+      # @raise [RosettAi::CompositionError] if strategy name is unknown
+      def self.resolve(name)
+        case name.to_s
+        when 'first_wins'  then FirstWins
+        when 'deep_merge'  then DeepMerge
+        when 'array_union' then ArrayUnion
+        else
+          raise RosettAi::CompositionError,
+                "Unknown merge strategy: #{name}. Valid: #{STRATEGIES.join(', ')}"
+        end
+      end
+
+      # Groups rules by ID while preserving insertion order.
+      #
+      # @param rules [Array<Hash>] rules with :id key
+      # @return [Array<Array(String, Array<Hash>)>] ordered [id, group] pairs
+      def self.group_by_id(rules)
+        groups = rules.group_by { |r| r[:id] }
+        seen = {}
+        rules.filter_map do |rule|
+          id = rule[:id]
+          next if seen.key?(id)
+
+          seen[id] = true
+          [id, groups[id]]
+        end
+      end
+
+      # First-wins strategy: the highest-priority (first in sorted order)
+      # rule wins. Duplicate IDs from lower-priority scopes are dropped.
+      # This is the default behaviour and matches pre-merge-strategy semantics.
+      class FirstWins
+        # @param rules [Array<Hash>] sorted rules (highest priority first)
+        # @return [Array<Hash>] deduplicated rules (first occurrence wins)
+        def apply(rules)
+          MergeStrategy.group_by_id(rules).map { |_id, group| group.first }
+        end
+      end
+
+      # Deep-merge strategy: when the same rule ID exists in multiple scopes,
+      # hash fields from all occurrences are recursively merged. Higher-priority
+      # values take precedence for scalar fields.
+      class DeepMerge
+        # @param rules [Array<Hash>] sorted rules (highest priority first)
+        # @return [Array<Hash>] merged rules (hashes deep-merged by ID)
+        def apply(rules)
+          MergeStrategy.group_by_id(rules).map do |_id, group|
+            next group.first if group.size == 1
+
+            merge_group(group)
+          end
+        end
+
+        private
+
+        def merge_group(group)
+          # Reverse so lowest-priority is merged first, highest-priority wins
+          group.reverse.reduce({}) { |merged, rule| deep_merge_hashes(merged, rule) }
+        end
+
+        def deep_merge_hashes(base, override)
+          base.merge(override) do |_key, old_val, new_val|
+            if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+              deep_merge_hashes(old_val, new_val)
+            else
+              new_val
+            end
+          end
+        end
+      end
+
+      # Array-union strategy: when the same rule ID exists in multiple scopes,
+      # array fields are combined (union) and deduplicated. Scalar fields use
+      # highest-priority value.
+      class ArrayUnion
+        # @param rules [Array<Hash>] sorted rules (highest priority first)
+        # @return [Array<Hash>] merged rules (arrays unioned by ID)
+        def apply(rules)
+          MergeStrategy.group_by_id(rules).map do |_id, group|
+            next group.first if group.size == 1
+
+            merge_group(group)
+          end
+        end
+
+        private
+
+        def merge_group(group)
+          # Start with highest-priority, union arrays from lower-priority
+          group.reduce({}) do |merged, rule|
+            if merged.empty?
+              rule
+            else
+              union_merge(merged, rule)
+            end
+          end
+        end
+
+        def union_merge(base, other)
+          base.merge(other) do |_key, old_val, new_val|
+            if old_val.is_a?(Array) && new_val.is_a?(Array)
+              (old_val | new_val)
+            else
+              old_val # higher-priority wins for non-arrays
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/composition/priority_sorter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Composition
+    # Sorts rules by priority within their scope.
+    # Lower priority numbers are higher importance (1 = most important).
+    # Equal-priority rules within the same scope are ordered by behaviour
+    # name alphabetically for deterministic output.
+    class PrioritySorter
+      # Sorts an array of annotated rules by scope weight, then priority,
+      # then behaviour name.
+      #
+      # @param rules [Array<Hash>] rules with :scope_weight, :priority, :behaviour_name keys
+      # @return [Array<Hash>] sorted rules (stable, deterministic)
+      def sort_rules(rules)
+        rules.sort_by do |rule|
+          [
+            -(rule[:scope_weight] || 0), # higher scope weight first (negate for ascending sort)
+            rule[:priority] || 50,        # lower priority number first
+            rule[:behaviour_name].to_s    # alphabetical tie-break
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/composition/scope_resolver.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Composition
+    # Resolves the scope hierarchy for behaviour files.
+    # Scopes are ordered: global > organisation > project > local.
+    # Later scopes override earlier ones at equal priority.
+    class ScopeResolver
+      # Ordered scope names from lowest to highest precedence.
+      SCOPE_ORDER = ['global', 'organisation', 'project', 'local'].freeze
+
+      # Numeric weight for each scope (higher = takes precedence).
+      SCOPE_WEIGHTS = SCOPE_ORDER.each_with_index.to_h { |scope, i| [scope, i] }.freeze
+
+      # Resolves the scope for a given behaviour file path.
+      #
+      # @param file_path [String, Pathname] path to the behaviour file
+      # @param project_root [Pathname, nil] detected project root
+      # @return [String] one of SCOPE_ORDER values
+      def resolve(file_path, project_root: nil)
+        path = file_path.to_s
+
+        if project_root && path.start_with?(project_root.join('.rosett-ai', 'conf', 'behaviour').to_s)
+          'project'
+        elsif path.include?('/organisation/') || path.include?('/org/')
+          'organisation'
+        elsif path.include?('/local/')
+          'local'
+        else
+          'global'
+        end
+      end
+
+      # Returns the numeric weight for a scope name.
+      #
+      # @param scope [String] scope name
+      # @return [Integer] weight (higher = overrides lower)
+      def weight(scope)
+        SCOPE_WEIGHTS.fetch(scope, 0)
+      end
+
+      # Compares two scopes. Returns true if scope_a overrides scope_b.
+      #
+      # @param scope_a [String] candidate overriding scope
+      # @param scope_b [String] candidate overridden scope
+      # @return [Boolean]
+      def overrides?(scope_a, scope_b)
+        weight(scope_a) > weight(scope_b)
+      end
+    end
+  end
+end

data/lib/rosett_ai/config/compile_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Config
+    # Structured result from compiling a single scope file.
+    #
+    # @!attribute scope [String] The scope name (managed, user, project, local)
+    # @!attribute source_path [Pathname] Path to the source YAML file
+    # @!attribute target_path [Pathname] Path to the target JSON file
+    # @!attribute json_data [Hash] The compiled JSON data (before serialization)
+    # @!attribute warnings [Array<String>] Advisory messages (version mismatch, missing env vars, etc.)
+    # @!attribute action [Symbol] One of :created, :updated, :unchanged, :skipped
+    # @!attribute diff [String, nil] Unified diff string (for simulate mode)
+    CompileResult = Struct.new(
+      :scope, :source_path, :target_path, :json_data,
+      :warnings, :action, :diff
+    ) do
+      def initialize(**)
+        super
+        self.warnings ||= []
+      end
+
+      # @return [Boolean] true if action is :created, :updated, or :unchanged
+      def success?
+        [:created, :updated, :unchanged].include?(action)
+      end
+
+      # @return [Boolean] true if action is :created or :updated
+      def changed?
+        [:created, :updated].include?(action)
+      end
+    end
+  end
+end

data/lib/rosett_ai/config/compiler.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Configuration subsystem.
+  module Config
+    # Deprecated — use RosettAiEngine::Claude::ConfigCompiler. Will be removed in v1.1.0.
+    # Only defined when rosett-ai-engine-claude gem is installed.
+    Compiler = RosettAiEngine::Claude::ConfigCompiler if defined?(RosettAiEngine::Claude::ConfigCompiler)
+  end
+end

data/lib/rosett_ai/config/domain_transformer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Configuration subsystem.
+  module Config
+    # Deprecated — use RosettAiEngine::Claude::DomainTransformer. Will be removed in v1.1.0.
+    # Only defined when rosett-ai-engine-claude gem is installed.
+    DomainTransformer = RosettAiEngine::Claude::DomainTransformer if defined?(RosettAiEngine::Claude::DomainTransformer)
+  end
+end

data/lib/rosett_ai/config/key_map.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Configuration subsystem.
+  module Config
+    # Deprecated — use RosettAiEngine::Claude::KeyMap. Will be removed in v1.1.0.
+    # Only defined when rosett-ai-engine-claude gem is installed.
+    KeyMap = RosettAiEngine::Claude::KeyMap if defined?(RosettAiEngine::Claude::KeyMap)
+  end
+end