igniter-contracts 0.5.2

data/lib/igniter/contracts/assembly/hook_specs.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      module HookSpecs
+        module_function
+
+        REGISTRY_SPECS = {
+          dsl_keywords: HookSpec.new(
+            registry: :dsl_keywords,
+            method_name: :call,
+            required_keywords: %i[builder],
+            role: :dsl_keyword,
+            return_policy: :opaque
+          ),
+          normalizers: HookSpec.new(
+            registry: :normalizers,
+            method_name: :call,
+            required_keywords: %i[operations profile],
+            role: :graph_transformer,
+            return_policy: :operations_array,
+            result_validator: HookResultPolicies.method(:operations_array)
+          ),
+          validators: HookSpec.new(
+            registry: :validators,
+            method_name: :call,
+            required_keywords: %i[operations profile],
+            role: :validator,
+            return_policy: :validation_findings,
+            result_validator: HookResultPolicies.method(:validation_findings)
+          ),
+          runtime_handlers: HookSpec.new(
+            registry: :runtime_handlers,
+            method_name: :call,
+            required_keywords: %i[operation state outputs inputs profile],
+            role: :runtime_handler,
+            return_policy: :value
+          ),
+          diagnostics_contributors: HookSpec.new(
+            registry: :diagnostics_contributors,
+            method_name: :augment,
+            required_keywords: %i[report result profile],
+            role: :diagnostics_contributor,
+            return_policy: :ignored
+          ),
+          effects: HookSpec.new(
+            registry: :effects,
+            method_name: :call,
+            required_keywords: %i[invocation],
+            role: :effect_adapter,
+            return_policy: :opaque
+          ),
+          executors: HookSpec.new(
+            registry: :executors,
+            method_name: :call,
+            required_keywords: %i[invocation],
+            role: :executor,
+            return_policy: :execution_result,
+            result_validator: HookResultPolicies.method(:execution_result)
+          )
+        }.freeze
+
+        def fetch(registry_name)
+          REGISTRY_SPECS.fetch(registry_name.to_sym)
+        end
+
+        def registry_names
+          REGISTRY_SPECS.keys
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/kernel.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      class Kernel
+        attr_reader :nodes,
+                    :dsl_keywords,
+                    :validators,
+                    :normalizers,
+                    :runtime_handlers,
+                    :diagnostics_contributors,
+                    :pack_manifests,
+                    :effects,
+                    :executors
+
+        def initialize(
+          nodes: Registry.new(name: :nodes),
+          dsl_keywords: Registry.new(name: :dsl_keywords),
+          validators: OrderedRegistry.new(name: :validators),
+          normalizers: OrderedRegistry.new(name: :normalizers),
+          runtime_handlers: Registry.new(name: :runtime_handlers),
+          diagnostics_contributors: OrderedRegistry.new(name: :diagnostics_contributors),
+          effects: Registry.new(name: :effects),
+          executors: Registry.new(name: :executors)
+        )
+          @nodes = nodes
+          @dsl_keywords = dsl_keywords
+          @validators = validators
+          @normalizers = normalizers
+          @runtime_handlers = runtime_handlers
+          @diagnostics_contributors = diagnostics_contributors
+          @pack_manifests = []
+          @effects = effects
+          @executors = executors
+          @finalized = false
+        end
+
+        def install(pack, installing: [])
+          raise FrozenKernelError, "kernel already finalized" if finalized?
+
+          manifest = pack.respond_to?(:manifest) ? pack.manifest : nil
+          pack_name = manifest&.name
+
+          return self if pack_name && pack_installed?(pack_name)
+
+          if pack_name && installing.include?(pack_name)
+            cycle = (installing + [pack_name]).join(" -> ")
+            raise CircularPackDependencyError, "circular pack dependency detected: #{cycle}"
+          end
+
+          install_required_packs(manifest, installing: [*installing, pack_name].compact) if manifest
+          register_pack_manifest(pack, manifest: manifest)
+          pack.install_into(self)
+          self
+        end
+
+        def finalize
+          validate_completeness!
+          validate_hook_implementations!
+          freeze_registries!
+          @finalized = true
+          Profile.build_from(self)
+        end
+
+        def finalized?
+          @finalized
+        end
+
+        private
+
+        REGISTRY_LABELS = {
+          dsl_keywords: "DSL keywords",
+          validators: "validators",
+          normalizers: "normalizers",
+          runtime_handlers: "runtime handlers",
+          diagnostics_contributors: "diagnostics contributors",
+          effects: "effects",
+          executors: "executors"
+        }.freeze
+
+        def register_pack_manifest(pack, manifest: nil)
+          manifest ||= pack.respond_to?(:manifest) ? pack.manifest : nil
+          return unless manifest
+
+          pack_manifests << manifest
+        end
+
+        def pack_installed?(name)
+          pack_manifests.any? { |manifest| manifest.name == name.to_sym }
+        end
+
+        def install_required_packs(manifest, installing:)
+          manifest.requires_packs.each do |dependency|
+            next if pack_installed?(dependency.name)
+
+            unless dependency.pack
+              raise UnknownPackDependencyError,
+                    "pack #{manifest.name} requires pack #{dependency.name}, but no pack implementation was provided"
+            end
+
+            install(dependency.pack, installing: installing)
+          end
+        end
+
+        def validate_completeness!
+          manifest_contracts = pack_manifests.flat_map(&:node_contracts)
+          undeclared_nodes = nodes.to_h.values.reject do |node|
+            manifest_contracts.any? do |contract|
+              contract.kind == node.kind
+            end
+          end
+          undeclared_contracts = undeclared_nodes.map do |node|
+            PackManifest.node(
+              node.kind,
+              requires_dsl: node.requires_dsl?,
+              requires_runtime: node.requires_runtime?
+            )
+          end
+          contracts = manifest_contracts + undeclared_contracts
+
+          missing_node_definitions = manifest_contracts.map(&:kind).reject { |kind| nodes.registered?(kind) }
+          missing_dsl = contracts.select(&:requires_dsl).map(&:kind).reject { |kind| dsl_keywords.registered?(kind) }
+          missing_runtime = contracts.select(&:requires_runtime).map(&:kind).reject do |kind|
+            runtime_handlers.registered?(kind)
+          end
+          missing_registry_contracts = collect_missing_registry_contracts
+          return if missing_node_definitions.empty? &&
+                    missing_dsl.empty? &&
+                    missing_runtime.empty? &&
+                    missing_registry_contracts.empty?
+
+          parts = []
+          parts << "missing node definitions for: #{missing_node_definitions.map(&:to_s).join(", ")}" unless missing_node_definitions.empty?
+          parts << "missing DSL keywords for: #{missing_dsl.map(&:to_s).join(", ")}" unless missing_dsl.empty?
+          parts << "missing runtime handlers for: #{missing_runtime.map(&:to_s).join(", ")}" unless missing_runtime.empty?
+          parts.concat(missing_registry_contracts)
+
+          raise IncompletePackError, parts.join("; ")
+        end
+
+        def validate_hook_implementations!
+          HookSpecs.registry_names.each do |registry_name|
+            hook_spec = HookSpecs.fetch(registry_name)
+
+            each_registry_entry(registry_name) do |key, implementation|
+              hook_spec.validate!(key, implementation)
+            end
+          end
+        end
+
+        def collect_missing_registry_contracts
+          pack_manifests
+            .flat_map(&:registry_contracts)
+            .group_by(&:registry)
+            .filter_map do |registry_name, contracts|
+              registry = registry_for(registry_name)
+              next if registry.nil?
+
+              missing = contracts.map(&:key).reject { |key| registry.registered?(key) }
+              next if missing.empty?
+
+              missing_registry_message(registry_name, missing)
+            end
+        end
+
+        def missing_registry_message(registry_name, missing)
+          label = REGISTRY_LABELS.fetch(registry_name, registry_name.to_s.tr("_", " "))
+          "missing #{label} for: #{missing.map(&:to_s).join(", ")}"
+        end
+
+        def registry_for(name)
+          case name.to_sym
+          when :dsl_keywords
+            dsl_keywords
+          when :validators
+            validators
+          when :normalizers
+            normalizers
+          when :runtime_handlers
+            runtime_handlers
+          when :diagnostics_contributors
+            diagnostics_contributors
+          when :effects
+            effects
+          when :executors
+            executors
+          end
+        end
+
+        def each_registry_entry(registry_name, &block)
+          registry = registry_for(registry_name)
+          return unless registry
+
+          case registry
+          when Registry
+            registry.to_h.each(&block)
+          when OrderedRegistry
+            registry.entries.each do |entry|
+              yield(entry.key, entry.value)
+            end
+          end
+        end
+
+        def freeze_registries!
+          [
+            nodes,
+            dsl_keywords,
+            validators,
+            normalizers,
+            runtime_handlers,
+            diagnostics_contributors,
+            effects,
+            executors
+          ].each(&:freeze!)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/node_type.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      NodeType = Struct.new(:kind, :metadata, keyword_init: true) do
+        def initialize(kind:, metadata: {})
+          normalized_metadata = {
+            requires_dsl: true,
+            requires_runtime: true
+          }.merge(metadata).freeze
+
+          super(kind: kind.to_sym, metadata: normalized_metadata)
+        end
+
+        def requires_dsl?
+          metadata.fetch(:requires_dsl, true)
+        end
+
+        def requires_runtime?
+          metadata.fetch(:requires_runtime, true)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/ordered_registry.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      class OrderedRegistry
+        Entry = Struct.new(:key, :value, keyword_init: true)
+
+        def initialize(name:)
+          @name = name
+          @entries = []
+          @keys = {}
+          @frozen = false
+        end
+
+        def register(key, value)
+          raise FrozenRegistryError, "#{@name} is frozen" if frozen?
+
+          normalized_key = normalize_key(key)
+          raise DuplicateRegistrationError, "#{@name} already has #{normalized_key}" if @keys.key?(normalized_key)
+
+          entry = Entry.new(key: normalized_key, value: value)
+          @entries << entry
+          @keys[normalized_key] = true
+          entry
+        end
+
+        def registered?(key)
+          @keys.key?(normalize_key(key))
+        end
+
+        def entries
+          @entries.dup
+        end
+
+        def freeze!
+          @frozen = true
+          @entries.freeze
+          @keys.freeze
+          self
+        end
+
+        def frozen?
+          @frozen
+        end
+
+        private
+
+        def normalize_key(key)
+          key.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/pack.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      module Pack
+        def install_into(_kernel)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/pack_manifest.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      class PackManifest
+        RegistryContract = Struct.new(:registry, :key, keyword_init: true) do
+          def initialize(registry:, key:)
+            super(
+              registry: registry.to_sym,
+              key: key.to_sym
+            )
+          end
+        end
+
+        NodeContract = Struct.new(:kind, :requires_dsl, :requires_runtime, keyword_init: true) do
+          def initialize(kind:, requires_dsl: true, requires_runtime: true)
+            super(
+              kind: kind.to_sym,
+              requires_dsl: requires_dsl,
+              requires_runtime: requires_runtime
+            )
+          end
+        end
+
+        PackDependency = Struct.new(:name, :pack, keyword_init: true) do
+          def initialize(name:, pack: nil)
+            super(
+              name: name.to_sym,
+              pack: pack
+            )
+          end
+        end
+
+        class << self
+          def node(kind, requires_dsl: true, requires_runtime: true)
+            NodeContract.new(
+              kind: kind,
+              requires_dsl: requires_dsl,
+              requires_runtime: requires_runtime
+            )
+          end
+
+          def registry(registry, key)
+            RegistryContract.new(registry: registry, key: key)
+          end
+
+          def dsl_keyword(key)
+            registry(:dsl_keywords, key)
+          end
+
+          def runtime_handler(key)
+            registry(:runtime_handlers, key)
+          end
+
+          def validator(key)
+            registry(:validators, key)
+          end
+
+          def normalizer(key)
+            registry(:normalizers, key)
+          end
+
+          def diagnostic(key)
+            registry(:diagnostics_contributors, key)
+          end
+
+          def effect(key)
+            registry(:effects, key)
+          end
+
+          def executor(key)
+            registry(:executors, key)
+          end
+
+          def pack_dependency(pack_or_name, pack: nil)
+            return PackDependency.new(name: pack_or_name, pack: pack) if pack
+
+            if pack_or_name.respond_to?(:manifest)
+              manifest = pack_or_name.manifest
+              return PackDependency.new(name: manifest.name, pack: pack_or_name)
+            end
+
+            PackDependency.new(name: pack_or_name)
+          end
+        end
+
+        attr_reader :name, :node_contracts, :registry_contracts, :metadata,
+                    :requires_packs, :provides_capabilities, :requires_capabilities
+
+        def initialize(name:, node_contracts: [], registry_contracts: [], diagnostics: [], metadata: {},
+                       requires_packs: [], provides_capabilities: [], requires_capabilities: [])
+          @name = name.to_sym
+          @node_contracts = node_contracts.freeze
+          @registry_contracts = (
+            registry_contracts +
+            diagnostics.map { |key| self.class.diagnostic(key) }
+          ).uniq.freeze
+          @metadata = metadata.freeze
+          @requires_packs = normalize_pack_dependencies(requires_packs)
+          @provides_capabilities = normalize_capabilities(provides_capabilities)
+          @requires_capabilities = normalize_capabilities(requires_capabilities)
+          freeze
+        end
+
+        def declared_keys_for(registry)
+          registry_contracts
+            .select { |contract| contract.registry == registry.to_sym }
+            .map(&:key)
+        end
+
+        def diagnostics
+          declared_keys_for(:diagnostics_contributors)
+        end
+
+        private
+
+        def normalize_pack_dependencies(dependencies)
+          Array(dependencies)
+            .map { |entry| entry.is_a?(PackDependency) ? entry : self.class.pack_dependency(entry) }
+            .uniq(&:name)
+            .freeze
+        end
+
+        def normalize_capabilities(capabilities)
+          Array(capabilities).flatten.compact.map(&:to_sym).uniq.freeze
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/path_access.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      module PathAccess
+        module_function
+
+        NO_DEFAULT = Object.new.freeze
+
+        def normalize_path(keyword_name:, key: nil, dig: nil)
+          raise ArgumentError, "#{keyword_name} accepts either key: or dig:, not both" if !key.nil? && !dig.nil?
+
+          raw_path =
+            if !key.nil?
+              [key]
+            elsif !dig.nil?
+              Array(dig)
+            else
+              raise ArgumentError, "#{keyword_name} requires key: or dig:"
+            end
+
+          raise ArgumentError, "#{keyword_name} dig: path cannot be empty" if raw_path.empty?
+
+          raw_path.map { |segment| normalize_segment(segment) }
+        end
+
+        def fetch_path(source, path, source_name:, keyword_name:, default: NO_DEFAULT)
+          current = source
+
+          path.each do |segment|
+            if segment_present?(current, segment)
+              current = fetch_segment(current, segment)
+            else
+              return default unless default.equal?(NO_DEFAULT)
+
+              raise KeyError, "#{keyword_name} path #{format_path(path)} not present in #{source_name}"
+            end
+          end
+
+          current
+        end
+
+        def normalize_segment(segment)
+          return segment if segment.is_a?(Integer)
+
+          segment.to_sym
+        end
+
+        def segment_present?(value, segment)
+          if value.respond_to?(:key?)
+            value.key?(segment) ||
+              (segment.is_a?(Symbol) && value.key?(segment.to_s)) ||
+              (segment.is_a?(String) && value.key?(segment.to_sym))
+          elsif value.is_a?(Array) && segment.is_a?(Integer)
+            segment >= 0 && segment < value.length
+          else
+            false
+          end
+        end
+
+        def fetch_segment(value, segment)
+          return value.fetch(segment) if value.respond_to?(:key?) && value.key?(segment)
+          return value.fetch(segment.to_s) if value.respond_to?(:key?) && segment.is_a?(Symbol) && value.key?(segment.to_s)
+          return value.fetch(segment.to_sym) if value.respond_to?(:key?) && segment.is_a?(String) && value.key?(segment.to_sym)
+
+          value.fetch(segment)
+        end
+
+        def format_path(path)
+          path.map(&:inspect).join(" -> ")
+        end
+      end
+    end
+  end
+end