disposita 0.1.0

data/lib/disposita/formats/yaml.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "psych"
+
+module Disposita
+  # Serialization codecs used by file sources.
+  # Supply a codec implementing load and dump through Sources::File.new.
+  module Formats
+    # Safe YAML codec used by the built-in file source.
+    #
+    # The codec deliberately accepts only ordinary data structures. Ruby object
+    # deserialization, Symbol tags and YAML aliases are disabled, preventing a
+    # configuration file from acting as an object-loading mechanism. Symbols in
+    # runtime configuration are serialized as plain strings and restored later
+    # by schema coercion when the declared type requires it.
+    #
+    # Consumers normally interact with this module indirectly through
+    # {Disposita::Sources::File}.
+    module YAML
+      module_function
+
+      # Decodes safe YAML into a configuration Hash.
+      #
+      # @param content [String] YAML document.
+      # @return [Hash] decoded mapping; an empty document becomes an empty Hash.
+      # @raise [Disposita::ParseError] if YAML is malformed, contains unsafe
+      #   constructs, or has a non-mapping document root.
+      def load(content)
+        data = Psych.safe_load(content, permitted_classes: [], permitted_symbols: [], aliases: false)
+        return {} if data.nil?
+        raise ParseError, "configuration root must be a mapping" unless data.is_a?(Hash)
+
+        data
+      rescue Psych::Exception => e
+        raise ParseError, "invalid YAML: #{e.message}"
+      end
+
+      # Encodes configuration data as safe, human-editable YAML.
+      #
+      # Hash keys and Symbols are converted to strings so emitted documents do
+      # not depend on Ruby-specific YAML tags.
+      #
+      # @param data [Hash] validated configuration payload.
+      # @return [String] YAML document.
+      def dump(data)
+        Psych.safe_dump(stringify(data), permitted_classes: [], permitted_symbols: [], aliases: false)
+      end
+
+      # Converts Ruby-oriented data to serialization-safe primitives.
+      #
+      # @param value [Object] nested configuration value.
+      # @return [Object] equivalent value containing string keys/symbols.
+      def stringify(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.to_s, stringify(child)] }
+        when Array
+          value.map { |child| stringify(child) }
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/disposita/internal/deep_merge.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Disposita
+  # Implementation details shared by the public configuration API.
+  #
+  # Consumers should use Schema, Configuration and Source instead of coupling
+  # integrations to these helpers, which may change without public API guarantees.
+  # @api private
+  module Internal
+    # Implements Disposita's default layer merge semantics.
+    #
+    # Nested hashes are merged recursively so namespaces can be overridden one
+    # setting at a time. Arrays and scalar values are replaced wholesale because
+    # concatenating them would introduce domain-specific semantics the schema did
+    # not explicitly request.
+    #
+    # @api private
+    module DeepMerge
+      module_function
+
+      # @param left [Hash] lower-precedence values.
+      # @param right [Hash] higher-precedence values.
+      # @return [Hash] merged representation.
+      def call(left, right)
+        left.merge(right) do |_key, old_value, new_value|
+          if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+            call(old_value, new_value)
+          else
+            new_value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/disposita/internal/definition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Disposita
+  module Internal
+    # Sentinel distinguishing "no default declared" from an explicit nil default.
+    # @api private
+    UNDEFINED = Object.new.freeze
+
+    # Immutable internal record describing one leaf setting in a schema.
+    #
+    # DSL input is normalized into this value object so resolution, validation,
+    # introspection and persistence operate on one stable representation.
+    #
+    # @api private
+    SettingDefinition = Data.define(
+      :path,
+      :type,
+      :default,
+      :required,
+      :env,
+      :secret,
+      :description,
+      :coerce,
+      :validator
+    ) do
+      # @return [String] dotted setting path used in diagnostics.
+      def key = path.join(".")
+
+      # @return [Boolean] whether an explicit default was declared, including nil.
+      def default? = !default.equal?(UNDEFINED)
+
+      # @return [Boolean] whether diagnostics must redact this setting.
+      def secret? = secret
+
+      # @return [Boolean] whether the setting must exist after resolution.
+      def required? = required
+
+      # @return [Boolean] whether raw values may be coerced to the declared type.
+      def coerce? = coerce
+    end
+  end
+end

data/lib/disposita/internal/hash_tools.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Disposita
+  module Internal
+    # Recursive Hash helpers shared by schema resolution and immutable output.
+    #
+    # These operations deliberately work only with ordinary Ruby containers and
+    # never use Marshal or object deserialization as a copying mechanism.
+    #
+    # @api private
+    module HashTools
+      module_function
+
+      # Normalizes nested mapping keys to Symbols, including mappings inside arrays.
+      # @param value [Object] raw tree.
+      # @return [Object] normalized tree.
+      def symbolize(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child), result|
+            result[key.to_sym] = symbolize(child)
+          end
+        when Array
+          value.map { |child| symbolize(child) }
+        else
+          value
+        end
+      end
+
+      # Reads a nested path without confusing an absent value with nil.
+      # @param hash [Hash] tree to inspect.
+      # @param path [Array<Symbol>] leaf path.
+      # @return [Object] value or UNDEFINED when absent.
+      def get(hash, path)
+        path.reduce(hash) do |current, segment|
+          return UNDEFINED unless current.is_a?(Hash) && current.key?(segment)
+
+          current[segment]
+        end
+      end
+
+      # Assigns a leaf value, creating intermediate namespace hashes as needed.
+      # @param hash [Hash] tree to update.
+      # @param path [Array<Symbol>] non-empty leaf path.
+      # @param value [Object] value to assign.
+      # @return [Hash] updated tree.
+      def set(hash, path, value)
+        cursor = hash
+        path[0...-1].each { |segment| cursor = (cursor[segment] ||= {}) }
+        cursor[path.last] = value
+        hash
+      end
+
+      # Collects leaf paths for unknown-setting checks and provenance.
+      # @param hash [Hash] tree to traverse.
+      # @param prefix [Array<Symbol>] parent path.
+      # @param result [Array<Array<Symbol>>] accumulator.
+      # @return [Array<Array<Symbol>>] leaf paths.
+      def flatten_keys(hash, prefix = [], result = [])
+        hash.each do |key, value|
+          path = prefix + [key.to_sym]
+          value.is_a?(Hash) ? flatten_keys(value, path, result) : result << path
+        end
+        result
+      end
+
+      # Copies containers and values so exports do not mutate configuration.
+      # @param value [Object] tree to copy.
+      # @return [Object] detached copy, or original for non-duplicable values.
+      def deep_dup(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [deep_dup(key), deep_dup(child)] }
+        when Array
+          value.map { |child| deep_dup(child) }
+        else
+          value.dup
+        end
+      rescue TypeError
+        value
+      end
+
+      # Freezes a tree recursively, including mapping keys and array members.
+      # @param value [Object] tree to freeze in place.
+      # @return [Object] frozen tree.
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each do |key, child|
+            deep_freeze(key)
+            deep_freeze(child)
+          end
+        when Array
+          value.each { |child| deep_freeze(child) }
+        end
+        value.freeze
+      end
+    end
+  end
+end

data/lib/disposita/internal/schema_builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Disposita
+  module Internal
+    # Evaluates the schema declaration DSL and records setting definitions.
+    #
+    # The builder is intentionally private. Public callers keep the immutable
+    # {Disposita::Schema} returned by +Disposita.define+ rather than retaining
+    # mutable DSL state.
+    #
+    # @api private
+    class SchemaBuilder
+      # @return [Array<SettingDefinition>] definitions accumulated by this root
+      #   builder and its nested namespace builders.
+      attr_reader :settings
+
+      # @param prefix [Array<Symbol>] namespace path for this builder.
+      # @param settings [Array<SettingDefinition>] shared definition collection.
+      def initialize(prefix: [], settings: [])
+        @prefix = prefix
+        @settings = settings
+      end
+
+      # Declares a nested namespace and evaluates its block in a child builder.
+      #
+      # @param name [String, Symbol] namespace segment.
+      # @yield nested schema DSL.
+      # @return [Object] result of evaluating the namespace block.
+      # @raise [SchemaError] when the name is invalid.
+      def namespace(name, &)
+        validate_name!(name)
+        self.class.new(prefix: @prefix + [name.to_sym], settings: settings).instance_eval(&)
+      end
+
+      # Declares one leaf configuration setting.
+      #
+      # The validator block belongs to the consumer's schema semantics; Disposita
+      # merely invokes it after type coercion. +optional+ currently exists to
+      # make intent explicit and to detect contradictory declarations; absence is
+      # otherwise optional unless +required: true+ is used.
+      #
+      # @param name [String, Symbol] leaf setting name.
+      # @param type [Object] Ruby class or type-like object understood by
+      #   TypeAdapter.
+      # @param default [Object] default value, or UNDEFINED when absent.
+      # @param required [Boolean] whether resolution must produce the setting.
+      # @param optional [Boolean] explicit optional marker.
+      # @param env [String, nil] explicit environment variable name.
+      # @param secret [Boolean] whether diagnostics must redact the value.
+      # @param description [String, nil] user-facing documentation text.
+      # @param coerce [Boolean] whether raw values may be coerced.
+      # @yieldparam value [Object] coerced value for custom validation.
+      # @yieldreturn [Boolean] truthy when the value is valid.
+      # @raise [SchemaError] for contradictory or duplicate definitions.
+      def setting(name, type:, default: UNDEFINED, required: false, optional: false,
+                  env: nil, secret: false, description: nil, coerce: true, &validator)
+        validate_name!(name)
+        validate_presence!(required, optional, default)
+        path = @prefix + [name.to_sym]
+        reject_duplicate!(path)
+
+        settings << SettingDefinition.new(
+          path: path.freeze,
+          type: type,
+          default: default,
+          required: required,
+          env: env,
+          secret: secret,
+          description: description,
+          coerce: coerce,
+          validator: validator
+        )
+      end
+
+      private
+
+      def validate_presence!(required, optional, default)
+        raise SchemaError, "required and optional cannot both be true" if required && optional
+        return unless required && !default.equal?(UNDEFINED)
+
+        raise SchemaError, "required settings cannot declare a default"
+      end
+
+      def reject_duplicate!(path)
+        return unless settings.any? { |item| item.path == path }
+
+        raise SchemaError, "duplicate setting: #{path.join('.')}"
+      end
+
+      def validate_name!(name)
+        return if name.is_a?(String) || name.is_a?(Symbol)
+
+        raise SchemaError, "names must be String or Symbol"
+      end
+    end
+  end
+end

data/lib/disposita/internal/type_adapter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Disposita
+  module Internal
+    # Bridges Ruby classes and type-like objects used by Disposita schemas.
+    #
+    # The adapter intentionally defines a very small protocol: a custom type may
+    # implement +valid?+ and optionally +coerce+. Otherwise normal Ruby case
+    # equality (===) is used for validation and a small set of primitive
+    # coercions is provided for configuration-friendly classes.
+    #
+    # Keeping this behind Internal lets Disposita later share or replace the type
+    # machinery without making Typio or another Rubcraft gem a hard dependency.
+    #
+    # @api private
+    module TypeAdapter
+      module_function
+
+      # @param type [Object] declared type.
+      # @param value [Object] candidate value.
+      # @return [Boolean] whether the value already satisfies the type.
+      def valid?(type, value)
+        return type.valid?(value) if type.respond_to?(:valid?)
+
+        type === value # rubocop:disable Style/CaseEquality -- Ruby case equality is the supported type protocol.
+      end
+
+      # Coerces a raw configuration value to a declared type.
+      #
+      # @param type [Object] declared type.
+      # @param value [Object] raw value.
+      # @return [Object] coerced value.
+      # @raise [CoercionError] when no safe conversion is available.
+      def coerce(type, value)
+        return value if valid?(type, value)
+        return type.coerce(value) if type.respond_to?(:coerce)
+
+        coerce_primitive(type, value)
+      rescue ArgumentError, TypeError => e
+        raise CoercionError, "cannot coerce #{value.inspect} to #{describe(type)}: #{e.message}"
+      end
+
+      # Converts built-in scalar types after custom protocols have been checked.
+      # @param type [Object] declared type.
+      # @param value [Object] raw value.
+      # @return [Object] converted scalar.
+      # @raise [ArgumentError, TypeError] when conversion is unavailable or invalid.
+      def coerce_primitive(type, value)
+        case type.respond_to?(:name) ? type.name : nil
+        when "String"
+          value.to_s
+        when "Integer"
+          Integer(value, 10)
+        when "Float"
+          Float(value)
+        when "Symbol"
+          value.is_a?(String) ? value.to_sym : raise(ArgumentError, "expected String")
+        else
+          raise ArgumentError, "no coercion available"
+        end
+      end
+
+      # @param type [Object] declared type.
+      # @return [String] human-readable type name for diagnostics.
+      def describe(type)
+        type.respond_to?(:name) && type.name ? type.name : type.inspect
+      end
+    end
+  end
+end

data/lib/disposita/paths.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Disposita
+  # Cross-platform helpers for conventional configuration locations.
+  #
+  # Disposita owns only the mechanics of finding conventional user-level paths.
+  # The consumer still owns application names, filenames and project-local path
+  # conventions. In particular, Disposita never imposes a +.rubcraft+ or
+  # +.disposita+ directory on project repositories.
+  #
+  # User paths follow platform conventions: XDG on Linux/Unix when available,
+  # Application Support on macOS and APPDATA/LOCALAPPDATA on Windows.
+  module Paths
+    module_function
+
+    # Returns the conventional per-user configuration directory for an app.
+    #
+    # Supplying +env+ and +host_os+ explicitly makes the method deterministic in
+    # tests and lets embedding applications control which process environment
+    # is observed.
+    #
+    # @param application [String, Symbol] application/domain directory name.
+    # @param env [Hash] environment-like mapping used to find HOME/XDG/APPDATA.
+    # @param host_os [String] operating-system identifier, usually Ruby's
+    #   +RbConfig::CONFIG["host_os"]+.
+    # @return [String] absolute or platform-native user configuration directory.
+    # @raise [Disposita::PathError] if the application name is empty or no base
+    #   user configuration directory can be determined.
+    # @example
+    #   Disposita::Paths.user_config("scm")
+    #   # Linux:   ~/.config/scm
+    #   # macOS:   ~/Library/Application Support/scm
+    #   # Windows: %APPDATA%\\scm
+    def user_config(application, env: ENV, host_os: RbConfig::CONFIG["host_os"])
+      name = application.to_s
+      raise PathError, "application name cannot be empty" if name.empty?
+
+      base = config_home(env, host_os)
+
+      raise PathError, "cannot determine user configuration directory" unless base
+
+      ::File.join(base, name)
+    end
+
+    # Selects the platform base directory before appending a consumer name.
+    # @api private
+    # @param env [Hash] environment-like mapping.
+    # @param host_os [String] platform identifier.
+    # @return [String, nil] base directory when available.
+    def config_home(env, host_os)
+      return env["APPDATA"] || env["LOCALAPPDATA"] if windows?(host_os)
+      return home_path(env, "Library", "Application Support") if macos?(host_os)
+
+      env["XDG_CONFIG_HOME"] || home_path(env, ".config")
+    end
+
+    # Appends platform-specific directories to HOME when it is available.
+    # @api private
+    # @param env [Hash] environment-like mapping.
+    # @param segments [Array<String>] directory names.
+    # @return [String, nil] path under HOME.
+    def home_path(env, *segments)
+      ::File.join(env["HOME"], *segments) if env["HOME"]
+    end
+    private_class_method :config_home, :home_path
+
+    # Resolves a consumer-selected path inside a project root.
+    #
+    # The method protects against +..+ traversal escaping the supplied root. It
+    # does not choose the relative filename or directory; that policy belongs to
+    # the application using Disposita.
+    #
+    # @param root [String] project root.
+    # @param relative [String] relative path chosen by the consumer.
+    # @return [String] expanded path contained by +root+.
+    # @raise [Disposita::PathError] when the resolved path escapes +root+.
+    # @example
+    #   Disposita::Paths.project(Dir.pwd, ".rubcraft/scm.yml")
+    def project(root, relative)
+      root = ::File.expand_path(root)
+      candidate = ::File.expand_path(relative, root)
+      unless candidate == root || candidate.start_with?("#{root}#{::File::SEPARATOR}")
+        raise PathError, "project configuration path escapes project root"
+      end
+
+      candidate
+    end
+
+    # @param host_os [String] Ruby host OS identifier.
+    # @return [Boolean] whether the identifier represents Windows.
+    def windows?(host_os) = host_os.match?(/mswin|mingw|cygwin/i)
+
+    # @param host_os [String] Ruby host OS identifier.
+    # @return [Boolean] whether the identifier represents macOS.
+    def macos?(host_os) = host_os.match?(/darwin/i)
+  end
+end