moose-inventory 2.0 → 2.1.1

data/lib/moose_inventory/operations/inventory_snapshot_preview.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Moose
+  module Inventory
+    module Operations
+      # Builds a non-mutating preview/diff for an already-validated inventory snapshot.
+      # rubocop:disable Metrics/ClassLength
+      class InventorySnapshotPreview
+        def initialize(context:)
+          @context = context
+        end
+
+        def call(snapshot:)
+          preview = empty_preview
+          preview_existing_entities(snapshot, preview)
+          preview_group_payloads(snapshot.fetch('groups'), preview)
+          preview_host_payloads(snapshot.fetch('hosts'), preview)
+          preview_ignored_existing(snapshot, preview)
+          preview
+        end
+
+        private
+
+        attr_reader :context
+
+        def empty_preview
+          {
+            'schema_version' => 'snapshot-import-preview-v1',
+            'changes_applied' => false,
+            'summary' => {
+              'hosts_created' => 0,
+              'groups_created' => 0,
+              'variables_changed' => 0,
+              'associations_added' => 0,
+              'unchanged' => 0,
+              'ignored_existing_hosts' => 0,
+              'ignored_existing_groups' => 0,
+              'destructive_changes' => 0
+            },
+            'creates' => { 'hosts' => [], 'groups' => [] },
+            'updates' => { 'host_vars' => [], 'group_vars' => [] },
+            'associations' => { 'host_groups' => [], 'group_children' => [], 'tags' => [] },
+            'unchanged' => {
+              'hosts' => [], 'groups' => [], 'host_vars' => [], 'group_vars' => [], 'associations' => []
+            },
+            'ignored' => { 'existing_hosts_not_in_snapshot' => [], 'existing_groups_not_in_snapshot' => [] },
+            'unsupported_destructive_implications' => []
+          }
+        end
+
+        def preview_existing_entities(snapshot, preview)
+          snapshot.fetch('groups').each_key do |name|
+            if context.find_group(name).nil?
+              add_create(preview, 'groups', name, 'groups_created')
+            else
+              add_unchanged(preview, 'groups', name)
+            end
+          end
+
+          snapshot.fetch('hosts').each_key do |name|
+            if context.find_host(name).nil?
+              add_create(preview, 'hosts', name, 'hosts_created')
+            else
+              add_unchanged(preview, 'hosts', name)
+            end
+          end
+        end
+
+        def preview_group_payloads(groups, preview)
+          groups.each do |name, payload|
+            group = context.find_group(name)
+            preview_variables(preview, group, :group, name, payload.fetch('vars', {}))
+            preview_tags(preview, group, 'group', name, array_value(payload, 'tags'))
+            array_value(payload, 'children').each do |child_name|
+              preview_association(preview, group, 'group_children', name, child_name) do |entity|
+                entity.children_dataset[name: child_name]
+              end
+            end
+          end
+        end
+
+        def preview_host_payloads(hosts, preview)
+          hosts.each do |name, payload|
+            host = context.find_host(name)
+            preview_variables(preview, host, :host, name, payload.fetch('vars', {}))
+            preview_tags(preview, host, 'host', name, array_value(payload, 'tags'))
+            array_value(payload, 'groups').each do |group_name|
+              preview_association(preview, host, 'host_groups', name, group_name) do |entity|
+                entity.groups_dataset[name: group_name]
+              end
+            end
+          end
+        end
+
+        def preview_variables(preview, entity, type, entity_name, variables)
+          variables.each do |name, value|
+            existing = entity&.public_send("#{type}vars_dataset")&.[](name: name)
+            entry = { 'entity' => entity_name, 'name' => name, 'to' => value.to_s }
+            if existing.nil?
+              add_update(preview, "#{type}_vars", entry)
+            elsif existing.value != value.to_s
+              add_update(preview, "#{type}_vars", entry.merge('from' => existing.value))
+            else
+              add_unchanged(preview, "#{type}_vars", entry)
+            end
+          end
+        end
+
+        def preview_tags(preview, entity, entity_type, entity_name, tags)
+          context.normalize_tag_names(tags).each do |tag_name|
+            entry = { 'entity_type' => entity_type, 'entity' => entity_name, 'tag' => tag_name }
+            if entity.nil? || entity.tags_dataset[name: tag_name].nil?
+              add_association(preview, 'tags', entry)
+            else
+              add_unchanged(preview, 'associations', entry)
+            end
+          end
+        end
+
+        def preview_association(preview, entity, key, source, target)
+          entry = { 'source' => source, 'target' => target }
+          if entity.nil? || yield(entity).nil?
+            add_association(preview, key, entry)
+          else
+            add_unchanged(preview, 'associations', entry.merge('type' => key))
+          end
+        end
+
+        def preview_ignored_existing(snapshot, preview)
+          snapshot_hosts = snapshot.fetch('hosts').keys
+          context.all_hosts.each do |host|
+            next if snapshot_hosts.include?(host.name)
+
+            preview['ignored']['existing_hosts_not_in_snapshot'] << host.name
+            preview['summary']['ignored_existing_hosts'] += 1
+          end
+
+          snapshot_groups = snapshot.fetch('groups').keys
+          context.all_groups.each do |group|
+            next if snapshot_groups.include?(group.name)
+
+            preview['ignored']['existing_groups_not_in_snapshot'] << group.name
+            preview['summary']['ignored_existing_groups'] += 1
+          end
+        end
+
+        def add_create(preview, key, value, counter)
+          preview['creates'][key] << value
+          preview['summary'][counter] += 1
+        end
+
+        def add_update(preview, key, entry)
+          preview['updates'][key] << entry
+          preview['summary']['variables_changed'] += 1
+        end
+
+        def add_association(preview, key, entry)
+          preview['associations'][key] << entry
+          preview['summary']['associations_added'] += 1
+        end
+
+        def add_unchanged(preview, key, entry)
+          preview['unchanged'][key] << entry
+          preview['summary']['unchanged'] += 1
+        end
+
+        def array_value(payload, key)
+          payload.fetch(key, []).map(&:to_s)
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end

data/lib/moose_inventory/operations/inventory_snapshot_validator.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Moose
+  module Inventory
+    module Operations
+      # Validates group hierarchy cycle safety without recursive traversal.
+      class GroupCycleValidator
+        def initialize(context:)
+          @context = context
+        end
+
+        def call(groups)
+          visiting = {}
+          visited = {}
+
+          groups.each_key do |root|
+            validate_from_root!(root, groups, visiting, visited)
+          end
+        end
+
+        private
+
+        attr_reader :context
+
+        def validate_from_root!(root, groups, visiting, visited)
+          stack = [[root, false]]
+          until stack.empty?
+            name, expanded = stack.pop
+            next if visited[name]
+
+            if expanded
+              visiting.delete(name)
+              visited[name] = true
+            else
+              queue_group_children!(name, groups, visiting, stack)
+            end
+          end
+        end
+
+        def queue_group_children!(name, groups, visiting, stack)
+          raise_invalid("group hierarchy contains a cycle at '#{name}'") if visiting[name]
+
+          visiting[name] = true
+          stack << [name, true]
+          array_value(groups[name], 'children', label: "group '#{name}' children").reverse_each do |child_name|
+            raise_invalid("group hierarchy contains a cycle at '#{child_name}'") if visiting[child_name]
+
+            stack << [child_name, false]
+          end
+        end
+
+        def array_value(payload, key, label:)
+          value = payload.fetch(key, [])
+          raise_invalid("#{label} must be a list") unless value.is_a?(Array)
+
+          value.map(&:to_s)
+        end
+
+        def raise_invalid(message)
+          raise context.moose_exception_class, "Invalid inventory snapshot: #{message}."
+        end
+      end
+
+      # Normalizes and validates portable inventory snapshot input before import.
+      class InventorySnapshotValidator
+        def initialize(context:)
+          @context = context
+        end
+
+        def call(snapshot:)
+          normalized = deep_stringify_keys(snapshot)
+          validate_snapshot!(normalized)
+          normalized
+        end
+
+        private
+
+        attr_reader :context
+
+        def validate_snapshot!(snapshot)
+          raise_invalid('snapshot must be a mapping') unless snapshot.is_a?(Hash)
+          raise_invalid('version must be 1') unless snapshot['version'].to_i == InventorySnapshot::VERSION
+          raise_invalid('hosts must be a mapping') unless snapshot['hosts'].is_a?(Hash)
+          raise_invalid('groups must be a mapping') unless snapshot['groups'].is_a?(Hash)
+
+          validate_hosts!(snapshot)
+          validate_groups!(snapshot)
+          validate_group_cycles!(snapshot['groups'])
+        end
+
+        def validate_hosts!(snapshot)
+          snapshot['hosts'].each do |name, payload|
+            validate_entity_payload!(name, payload, 'host', allowed_keys: %w[groups tags vars])
+            groups = array_value(payload, 'groups', label: "host '#{name}' groups")
+            groups.each do |group_name|
+              next if snapshot['groups'].key?(group_name)
+
+              raise_invalid("host '#{name}' references unknown group '#{group_name}'")
+            end
+          end
+        end
+
+        def validate_groups!(snapshot)
+          snapshot['groups'].each do |name, payload|
+            validate_entity_payload!(name, payload, 'group', allowed_keys: %w[children tags vars])
+            children = array_value(payload, 'children', label: "group '#{name}' children")
+            children.each do |child_name|
+              next if snapshot['groups'].key?(child_name)
+
+              raise_invalid("group '#{name}' references unknown child group '#{child_name}'")
+            end
+          end
+        end
+
+        def validate_entity_payload!(name, payload, label, allowed_keys:)
+          raise_invalid("#{label} name cannot be empty") if blank_string?(name)
+          raise_invalid("#{label} '#{name}' must be a mapping") unless payload.is_a?(Hash)
+
+          unsupported = payload.keys - allowed_keys
+          unless unsupported.empty?
+            raise_invalid("#{label} '#{name}' has unsupported fields: #{unsupported.join(', ')}")
+          end
+
+          variables = payload.fetch('vars', {})
+          raise_invalid("#{label} '#{name}' vars must be a mapping") unless variables.is_a?(Hash)
+          variables.each_key do |variable_name|
+            raise_invalid("#{label} '#{name}' variable name cannot be empty") if blank_string?(variable_name)
+          end
+
+          payload['tags'] = context.normalize_tag_names(array_value(payload, 'tags', label: "#{label} '#{name}' tags"))
+        end
+
+        def validate_group_cycles!(groups)
+          GroupCycleValidator.new(context: context).call(groups)
+        end
+
+        def array_value(payload, key, label:)
+          value = payload.fetch(key, [])
+          raise_invalid("#{label} must be a list") unless value.is_a?(Array)
+
+          value.map(&:to_s)
+        end
+
+        def deep_stringify_keys(value)
+          case value
+          when Hash
+            stringify_hash_keys(value)
+          when Array
+            value.map { |entry| deep_stringify_keys(entry) }
+          else
+            value
+          end
+        end
+
+        def stringify_hash_keys(hash)
+          hash.each_with_object({}) do |(key, val), result|
+            normalized_key = key.to_s
+            raise_invalid("duplicate normalized key '#{normalized_key}'") if result.key?(normalized_key)
+
+            result[normalized_key] = deep_stringify_keys(val)
+          end
+        end
+
+        def blank_string?(value)
+          value.to_s.strip.empty?
+        end
+
+        def raise_invalid(message)
+          raise context.moose_exception_class, "Invalid inventory snapshot: #{message}."
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/operations/operation_event_support.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Moose
+  module Inventory
+    module Operations
+      # Shared structured event/result plumbing for inventory operations.
+      module OperationEventSupport
+        Event = Struct.new(:type, :payload, keyword_init: true)
+        Result = Struct.new(:events, :warning_count, keyword_init: true)
+
+        private
+
+        def build_event(type, payload = {})
+          Event.new(type: type, payload: payload)
+        end
+
+        def emit(events, type, payload = {})
+          events << build_event(type, payload)
+        end
+
+        def operation_result(events:, warning_count: 0)
+          Result.new(events: events, warning_count: warning_count)
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/operations/query_inventory/base_query.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Moose
+  module Inventory
+    module Operations
+      class QueryInventory
+        # Shared helpers for query subcomponents.
+        class BaseQuery
+          def initialize(context:)
+            @context = context
+          end
+
+          private
+
+          attr_reader :context
+
+          def variables_hash(dataset)
+            dataset.order(:id).to_h { |variable| [variable[:name].to_sym, variable[:value]] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/operations/query_inventory/group_queries.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Moose
+  module Inventory
+    module Operations
+      class QueryInventory
+        # Group-focused read queries.
+        class GroupQueries < BaseQuery
+          def get_groups(names:)
+            names.each_with_object({}) do |name, results|
+              group = context.find_group(name)
+              next if group.nil?
+
+              results[group.name.to_sym] = group_data(group)
+            end
+          end
+
+          def list_groups(ansible:)
+            context.all_groups.each_with_object({}) do |group, results|
+              hosts = group.hosts_dataset.map(:name)
+              next if hide_empty_automatic_group?(group, hosts)
+
+              results[group.name.to_sym] = list_group_data(group, hosts, ansible: ansible)
+            end
+          end
+
+          def list_group_vars(names:, ansible:)
+            return {} if names.empty?
+            return ansible_group_vars(names.first) if ansible
+
+            names.each_with_object({}) do |name, results|
+              group = context.find_group(name)
+              next if group.nil?
+
+              results[name.to_sym] = variables_hash(group.groupvars_dataset)
+            end
+          end
+
+          private
+
+          def group_data(group)
+            {}.tap do |data|
+              hosts = group.hosts_dataset.map(:name)
+              data[:hosts] = hosts unless hosts.empty?
+
+              children = group.children_dataset.map(:name)
+              data[:children] = children unless children.empty?
+
+              groupvars = variables_hash(group.groupvars_dataset)
+              data[:groupvars] = groupvars unless groupvars.empty?
+            end
+          end
+
+          def hide_empty_automatic_group?(group, hosts)
+            group.name == 'ungrouped' && hosts.empty?
+          end
+
+          def list_group_data(group, hosts, ansible:)
+            {}.tap do |data|
+              data[:hosts] = hosts if ansible || !hosts.empty?
+
+              children = group.children_dataset.map(:name)
+              data[:children] = children unless children.empty?
+
+              append_group_vars(data, group, ansible: ansible)
+            end
+          end
+
+          def append_group_vars(data, group, ansible:)
+            groupvars = variables_hash(group.groupvars_dataset)
+            return if groupvars.empty?
+
+            data[ansible ? :vars : :groupvars] = groupvars
+          end
+
+          def ansible_group_vars(name)
+            group = context.find_group(name)
+            return {} if group.nil?
+
+            variables_hash(group.groupvars_dataset)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/operations/query_inventory/host_queries.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Moose
+  module Inventory
+    module Operations
+      class QueryInventory
+        # Host-focused read queries.
+        class HostQueries < BaseQuery
+          def get_hosts(names:)
+            names.each_with_object({}) do |name, results|
+              host = context.find_host(name)
+              next if host.nil?
+
+              results[host.name.to_sym] = host_data(host)
+            end
+          end
+
+          def list_hosts(filters: {})
+            dataset = filtered_hosts_dataset(filters)
+            return {} if dataset.nil?
+
+            dataset.order(:id).all.to_h do |host|
+              [host.name.to_sym, host_data(host)]
+            end
+          end
+
+          def list_host_vars(names:, ansible:)
+            return ansible_host_vars(names.first) if ansible
+
+            names.each_with_object({}) do |name, results|
+              host = context.find_host(name)
+              next if host.nil?
+
+              results[name.to_sym] = variables_hash(host.hostvars_dataset)
+            end
+          end
+
+          private
+
+          def host_data(host)
+            {}.tap do |data|
+              groups = host.groups_dataset.map(:name)
+              data[:groups] = groups unless groups.empty?
+
+              tags = host.tags_dataset.map(:name).sort
+              data[:tags] = tags unless tags.empty?
+
+              hostvars = variables_hash(host.hostvars_dataset)
+              data[:hostvars] = hostvars unless hostvars.empty?
+            end
+          end
+
+          def filtered_hosts_dataset(filters)
+            dataset = context.hosts_dataset
+            dataset = filter_hosts_by_groups(dataset, filters.fetch(:groups, []))
+            return nil if dataset.nil?
+
+            dataset = filter_hosts_by_tags(dataset, filters.fetch(:tags, []))
+            return nil if dataset.nil?
+
+            filter_hosts_by_variables(dataset, filters.fetch(:variables, {}))
+          end
+
+          def filter_hosts_by_groups(dataset, groups)
+            groups.reduce(dataset) do |current_dataset, group_name|
+              group = context.find_group(group_name)
+              return nil if group.nil?
+
+              current_dataset.where(id: context.db_dataset(:groups_hosts).where(group_id: group.id).select(:host_id))
+            end
+          end
+
+          def filter_hosts_by_tags(dataset, tags)
+            tags.reduce(dataset) do |current_dataset, tag_name|
+              tag = context.find_tag(tag_name)
+              return nil if tag.nil?
+
+              current_dataset.where(id: context.db_dataset(:hosts_tags).where(tag_id: tag.id).select(:host_id))
+            end
+          end
+
+          def filter_hosts_by_variables(dataset, variables)
+            variables.reduce(dataset) do |current_dataset, (name, value)|
+              current_dataset.where(
+                id: context.db_dataset(:hostvars).where(name: name, value: value).select(:host_id)
+              )
+            end
+          end
+
+          def ansible_host_vars(name)
+            results = {}
+            host = context.find_host(name)
+            results.merge!(variables_hash(host.hostvars_dataset)) unless host.nil?
+
+            results[:_meta] = {
+              hostvars: context.all_hosts.to_h do |entry|
+                [entry.name.to_sym, variables_hash(entry.hostvars_dataset)]
+              end
+            }
+            results
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/operations/query_inventory.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'query_inventory/base_query'
+require_relative 'query_inventory/host_queries'
+require_relative 'query_inventory/group_queries'
+
+module Moose
+  module Inventory
+    module Operations
+      # Read-only inventory query seam for host/group CLI commands.
+      class QueryInventory
+        def initialize(context:)
+          @host_queries = HostQueries.new(context: context)
+          @group_queries = GroupQueries.new(context: context)
+        end
+
+        def get_hosts(names:)
+          host_queries.get_hosts(names: names)
+        end
+
+        def list_hosts(filters: {})
+          host_queries.list_hosts(filters: filters)
+        end
+
+        def list_host_vars(names:, ansible:)
+          host_queries.list_host_vars(names: names, ansible: ansible)
+        end
+
+        def get_groups(names:)
+          group_queries.get_groups(names: names)
+        end
+
+        def list_groups(ansible:)
+          group_queries.list_groups(ansible: ansible)
+        end
+
+        def list_group_vars(names:, ansible:)
+          group_queries.list_group_vars(names: names, ansible: ansible)
+        end
+
+        private
+
+        attr_reader :group_queries, :host_queries
+      end
+    end
+  end
+end