disposita 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2fb4585036294fbe8e0879b28e7a2dcba238402e3719cdd4fabacf016af8f1ee
+  data.tar.gz: 6761b686729f6fb6042fb8e204c990bad8f7839197b2a9251bd2eb4b07b4c785
+SHA512:
+  metadata.gz: 99b4d980ac2044614b82a938f44edb69f63128ffa4e0edb86b2c3179e7905941d8de0daa5631c57e36a3a0dee8b6a9af2655e1d550c997503e86c266bb17cff3
+  data.tar.gz: 3c6c118173f448fc1b830c584f90d5dab96a641c6bfd3ab1b6ad28364ff3eb6ae28b85875b5c87055989d5a6fbcf07b7d73ce97cfb1810f9696f48953bdb6103

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to Disposita will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows Semantic Versioning.
+
+## [Unreleased]
+
+### Fixed
+
+- Load YARD correctly and keep Markdown out of Ruby source parsing; validate documentation in CI.
+- Redact secret defaults in schema metadata and preserve caller-owned path arrays.
+
+### Added
+
+- Complete namespace/helper documentation and regression coverage for source contracts, safe YAML and failed atomic writes.
+
+## [0.1.0] - 2026-09-04
+
+### Added
+
+- Consumer-owned schema DSL with nested namespaces.
+- Typed settings with conservative coercion and custom validation.
+- Defaults, required/optional settings and strict unknown-setting detection.
+- Boolean, enum and typed-array helpers for configuration-oriented types.
+- Immutable resolved configuration with dot access and detached hash export.
+- Explicit layered resolution and source provenance.
+- Environment source with explicit names or generated prefixes.
+- In-memory source for runtime overrides and tests.
+- Safe YAML loading and serialization.
+- Atomic YAML file persistence with explicit writable targets.
+- Secret metadata, diagnostic redaction and opt-in secret file persistence.
+- Cross-platform user configuration path helpers.
+- Schema introspection and schema version checks.
+- Structured Disposita error hierarchy.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rubcraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,322 @@
+# Disposita
+
+Declarative, typed and layered configuration infrastructure for Ruby applications, gems and CLIs.
+
+Disposita provides the mechanics of configuration while leaving ownership and meaning with the consumer. It does not know what `:ssh`, `production` or a timeout mean to your application; it only knows how those values are declared, loaded, coerced, validated, layered and persisted.
+
+## Why Disposita?
+
+Configuration tends to grow into repeated infrastructure: parsers, defaults, environment variables, per-user paths, project overrides, validation, persistence and diagnostics. Disposita centralizes that infrastructure without making a toolkit or framework the owner of every consumer's configuration.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "disposita"
+```
+
+Then run `bundle install`.
+
+## Define a schema
+
+```ruby
+require "disposita"
+
+SCMConfig = Disposita.define(:scm, version: 1) do
+  namespace :git do
+    setting :default_remote,
+      type: String,
+      default: "origin",
+      description: "Default Git remote"
+
+    setting :transport,
+      type: Disposita::Types.enum(:ssh, :https),
+      default: :ssh,
+      env: "SCM_GIT_TRANSPORT"
+
+    setting :timeout,
+      type: Integer,
+      default: 30
+
+    setting :token,
+      type: String,
+      secret: true,
+      optional: true
+  end
+end
+```
+
+`Disposita.define` returns a schema object. It does not register global mutable state and it performs no filesystem or environment reads by itself.
+
+### Setting options
+
+Within `Disposita.define`, `namespace(name) { ... }` groups settings; namespaces can nest.
+`setting(name, type:, ...) { |value| ... }` declares a leaf. Its optional validator runs after coercion and must return a truthy value.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `type:` | Required | Ruby class, a built-in type helper, or an object implementing `valid?` and optionally `coerce`. Otherwise validation uses `===`. |
+| `default:` | Absent | Value used when no source provides one. An explicit `nil` still counts as a default and must satisfy the declared type. |
+| `required:` | `false` | Reject resolution if the setting is absent. Cannot be combined with a default or `optional: true`. |
+| `optional:` | `false` | Explicitly documents that absence is allowed; settings are already optional unless required. |
+| `env:` | `nil` | Explicit variable name, taking precedence over generated names. |
+| `secret:` | `false` | Redact diagnostics and deny ordinary file persistence. |
+| `description:` | `nil` | Consumer-facing text returned by schema introspection. |
+| `coerce:` | `true` | Convert raw input before checking semantic validation. Set false for strict values. |
+
+`Schema#load` accepts no arguments for defaults-only resolution. `Schema#resolve` requires an explicit source or array; use `resolve([])` for defaults alone.
+
+## Resolve layers
+
+```ruby
+global = Disposita::Sources::File.new(
+  File.join(Disposita::Paths.user_config("scm"), "config.yml"),
+  name: :global
+)
+
+project = Disposita::Sources::File.new(
+  ".scm.yml",
+  name: :project
+)
+
+config = SCMConfig.load(
+  sources: [global, project],
+  env: ENV,
+  env_prefix: "SCM",
+  overrides: { git: { timeout: 10 } }
+)
+```
+
+Precedence is explicit and follows source order. Schema defaults are always the lowest layer; runtime overrides supplied to `load` are the highest layer.
+
+```text
+defaults < global < project < environment < runtime
+```
+
+## Typed access
+
+```ruby
+config.git.default_remote # => "origin"
+config.git.transport      # => :ssh
+config.git.timeout        # => 10
+```
+
+Resolved configuration is immutable. `to_h` returns a detached copy for interoperability.
+
+## Coercion
+
+Disposita performs conservative coercion when a setting allows it (the default):
+
+```text
+"5432"  -> Integer
+"1.5"   -> Float
+"ssh"   -> Symbol / enum value
+"false" -> Boolean
+```
+
+Use `coerce: false` to require an already-typed value.
+
+```ruby
+setting :strict_port, type: Integer, coerce: false
+```
+
+## Validation
+
+A setting can add consumer-owned semantic validation:
+
+```ruby
+setting :timeout, type: Integer, default: 30 do |value|
+  value.positive?
+end
+```
+
+Disposita runs the rule; the consumer defines what the rule means.
+
+## Environment variables
+
+A setting may name its environment variable explicitly:
+
+```ruby
+setting :transport, type: Symbol, env: "SCM_GIT_TRANSPORT"
+```
+
+Or a source may generate names from a prefix and setting path:
+
+```ruby
+Disposita::Sources::Environment.new(prefix: "SCM")
+# git.transport -> SCM_GIT_TRANSPORT
+```
+
+## Safe YAML
+
+The bundled file source uses `Psych.safe_load` and disables Ruby-object deserialization and YAML aliases. Symbols are serialized as strings and coerced back according to the schema.
+
+```yaml
+version: 1
+git:
+  transport: ssh
+```
+
+Disposita intentionally ships YAML only in 0.1.0. The format boundary is isolated so JSON or TOML can be added without changing schema ownership or resolution semantics.
+
+## Explicit writes
+
+Reading may combine many layers. Writing always targets one explicit writable source.
+
+```ruby
+project = Disposita::Sources::File.new(".scm.yml", name: :project)
+
+SCMConfig.write(project, git: { transport: :https })
+```
+
+Writes are validated and performed atomically through a temporary file followed by rename.
+
+Defaults are not written automatically: consumers persist only the overrides they choose.
+
+## Secrets
+
+A setting can be marked as sensitive:
+
+```ruby
+setting :token, type: String, secret: true
+```
+
+The actual value remains available to application code:
+
+```ruby
+config.git.token
+```
+
+But diagnostics redact it:
+
+```ruby
+config.inspect
+# => #<Disposita::Configuration git=#<... token=[REDACTED]>>
+```
+
+Normal file sources reject secret persistence by default. A consumer must opt in explicitly:
+
+```ruby
+private_store = Disposita::Sources::File.new(
+  "~/.config/scm/private.yml",
+  name: :private,
+  allow_secrets: true
+)
+```
+
+Secret-aware behavior is not encryption. Disposita 0.1.0 deliberately does not implement cryptographic storage, key management, Vault, KMS or OS keychains.
+
+## Provenance
+
+Disposita tracks which layer supplied the winning value:
+
+```ruby
+config.source_of("git.transport")
+# => :project
+
+config.explain("git.transport")
+# => { path: "git.transport", value: :https, source: :project }
+```
+
+Secret values are redacted from `explain`.
+
+## Paths
+
+User-level configuration paths follow platform conventions:
+
+- Linux: `$XDG_CONFIG_HOME/<app>` or `~/.config/<app>`
+- macOS: `~/Library/Application Support/<app>`
+- Windows: `%APPDATA%\<app>` (falling back to `%LOCALAPPDATA%`)
+
+Project paths remain consumer-owned:
+
+```ruby
+Disposita::Paths.project(Dir.pwd, ".rubcraft/scm.yml")
+```
+
+Disposita never imposes `.rubcraft`, `.disposita`, or another project directory.
+
+## Schema introspection
+
+```ruby
+SCMConfig.describe("git.transport")
+# => {
+#   path: "git.transport",
+#   type: "enum(:ssh, :https)",
+#   default: :ssh,
+#   has_default: true,
+#   required: false,
+#   secret: false,
+#   env: "SCM_GIT_TRANSPORT",
+#   description: nil
+# }
+```
+
+This metadata is intended to support future CLI help, documentation and UI tooling without coupling Disposita to a particular CLI framework. Secret defaults appear as `[REDACTED]`, while `has_default` still indicates whether a default exists. Direct configuration access and `to_h` return actual values.
+
+Prefer `describe` for diagnostic tooling. The lower-level `setting` and `settings` methods expose internal definition objects, including actual defaults; they are not safe logging representations.
+
+## Schema versions
+
+Each schema has a version and file sources may persist it. Disposita rejects configuration produced by a newer schema version. Automatic migrations are intentionally deferred beyond 0.1.0 so the migration contract can be designed without freezing a premature API.
+
+## Ownership model
+
+Disposita owns:
+
+- schema infrastructure
+- type checking and configuration-oriented coercion
+- loading and persistence primitives
+- layering and provenance
+- conventional user paths
+- validation mechanics
+- secret-aware diagnostics
+
+Consumers own:
+
+- the schema itself
+- project file locations
+- layer policy and precedence
+- what each setting means
+- semantic validation rules
+- whether and where secrets may be persisted
+
+A library such as SCM can remain configuration-agnostic while `SCM CLI`, Rubcraft Toolkit, or another application defines its own Disposita schema around SCM.
+
+## Non-goals for 0.1.0
+
+Disposita does not aim to be a general-purpose type system, secret manager, encryption framework, Rails settings singleton, command-line parser or business-rule engine.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+bundle exec rake
+COVERAGE=true bundle exec rspec
+bundle exec rake yard
+```
+
+The test suite is organized by public behavior and subsystem, with integration-style schema specs separated from source/format/path specs.
+
+## License
+
+MIT.
+
+## API documentation
+
+Disposita's public API is documented with YARD comments that explain not only
+method signatures, but also ownership, precedence, persistence safety and common
+usage patterns. Generate the local documentation with:
+
+```sh
+bundle exec rake yard
+```
+
+The generated site is written to `doc/`. CI generates it with warnings treated as failures. Internal implementation objects are
+marked with `@api private`; applications should build against the documented
+public objects such as `Disposita`, `Disposita::Schema`,
+`Disposita::Configuration`, `Disposita::Source`, `Disposita::Sources::*`,
+`Disposita::Types` and `Disposita::Paths`.

data/lib/disposita/configuration.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Disposita
+  # Immutable, typed configuration produced after all sources are resolved.
+  #
+  # Configuration is the object an application normally consumes at runtime.
+  # Values can be accessed through dot notation or brackets, but mutation is
+  # intentionally unsupported. {#to_h} returns a detached copy when a mutable
+  # representation is needed for interoperability.
+  #
+  # Every selected value retains provenance, allowing diagnostic tooling to
+  # explain whether it came from a default, global file, project file, ENV or a
+  # runtime override. Settings marked +secret: true+ are redacted from
+  # diagnostic representations such as {#inspect} and {#explain}.
+  #
+  # @example
+  #   config.server.port          # => 3000
+  #   config[:server][:port]      # => 3000
+  #   config.source_of("server.port") # => :default
+  #
+  # @see Disposita::Schema#resolve
+  class Configuration
+    # Read-only namespace node used to provide ergonomic nested access.
+    #
+    # Node deliberately wraps hashes instead of exposing them directly so the
+    # resolved configuration remains immutable and secret-aware diagnostics can
+    # be delegated back to the owning Configuration.
+    class Node
+      # @param data [Hash] subtree represented by this node.
+      # @param root [Disposita::Configuration] owning root configuration.
+      # @param path [Array<Symbol>] absolute path represented by this node.
+      def initialize(data, root:, path: [])
+        @data = data
+        @root = root
+        @path = path
+      end
+
+      # Reads a child setting or namespace by key.
+      #
+      # @param key [String, Symbol] immediate child name.
+      # @return [Object, Disposita::Configuration::Node] scalar value or nested
+      #   read-only node.
+      # @raise [KeyError] when the child is not present in the resolved data.
+      def [](key)
+        value_for(key)
+      end
+
+      # Returns a detached mutable Hash representation of this subtree.
+      #
+      # Changing the returned object never mutates the resolved configuration.
+      # This method returns actual secret values and should therefore not be
+      # treated as a safe logging representation.
+      #
+      # @return [Hash]
+      def to_h
+        Internal::HashTools.deep_dup(@data)
+      end
+
+      # Returns a secret-aware diagnostic representation.
+      #
+      # @return [String] representation with secret settings replaced by
+      #   +[REDACTED]+.
+      def inspect
+        @root.__send__(:inspect_node, @data, @path)
+      end
+
+      # Resolves dot access to a setting or namespace; unknown calls use Ruby lookup.
+      # @param name [Symbol] requested setting name.
+      # @param arguments [Array<Object>] arguments supplied by the caller.
+      # @return [Object] resolved setting or namespace.
+      # @raise [NoMethodError] for unknown names or calls with arguments.
+      def method_missing(name, *arguments)
+        return super unless arguments.empty? && @data.key?(name)
+
+        value_for(name)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @data.key?(name) || super
+      end
+
+      private
+
+      def value_for(key)
+        key = key.to_sym
+        raise KeyError, "unknown configuration key: #{(@path + [key]).join('.')}" unless @data.key?(key)
+
+        value = @data[key]
+        value.is_a?(Hash) ? self.class.new(value, root: @root, path: @path + [key]) : value
+      end
+    end
+
+    # @return [Disposita::Schema] schema that produced this configuration.
+    attr_reader :schema
+
+    # Builds an immutable resolved configuration.
+    #
+    # Applications normally receive instances from {Disposita::Schema#resolve}
+    # or {Disposita::Schema#load} rather than constructing them directly.
+    #
+    # @param schema [Disposita::Schema] owning schema.
+    # @param data [Hash] fully coerced and validated values.
+    # @param provenance [Hash{Array<Symbol> => Symbol}] selected source for each
+    #   resolved leaf setting.
+    def initialize(schema:, data:, provenance:)
+      @schema = schema
+      @data = Internal::HashTools.deep_freeze(data)
+      @provenance = provenance.freeze
+      @root = Node.new(@data, root: self)
+      freeze
+    end
+
+    # Reads a top-level setting or namespace.
+    #
+    # @param key [String, Symbol] top-level key.
+    # @return [Object, Disposita::Configuration::Node]
+    # @raise [KeyError] when the key is absent.
+    def [](key) = @root[key]
+
+    # Reports which source supplied the effective value for a setting.
+    #
+    # @param path [String, Array<String, Symbol>, Symbol] setting path.
+    # @return [Symbol, nil] source name, +:default+ for schema defaults, or +nil+
+    #   when no provenance entry exists.
+    # @example
+    #   config.source_of("git.transport") # => :project
+    def source_of(path)
+      @provenance[normalize_path(path)]
+    end
+
+    # Explains one effective setting without exposing secret values.
+    #
+    # This small stable structure is intended for diagnostics and CLI commands
+    # such as +config explain+. A secret setting reports +[REDACTED]+ even though
+    # direct application access still returns its real value.
+    #
+    # @param path [String, Array<String, Symbol>, Symbol] setting path.
+    # @return [Hash] frozen Hash containing +:path+, +:value+ and +:source+.
+    # @raise [KeyError] if the path is not declared by the schema.
+    def explain(path)
+      normalized = normalize_path(path)
+      setting = schema.setting(normalized)
+      raise KeyError, "unknown configuration key: #{normalized.join('.')}" unless setting
+
+      {
+        path: normalized.join("."),
+        value: setting.secret? ? "[REDACTED]" : Internal::HashTools.get(@data, normalized),
+        source: @provenance[normalized]
+      }.freeze
+    end
+
+    # Returns a detached mutable Hash containing resolved values.
+    #
+    # Unlike {#inspect}, this is a data export API and therefore includes actual
+    # secret values. Callers are responsible for avoiding accidental logging or
+    # persistence of the returned Hash.
+    #
+    # @return [Hash]
+    def to_h
+      Internal::HashTools.deep_dup(@data)
+    end
+
+    # Returns a secret-aware diagnostic representation of the configuration.
+    #
+    # @return [String]
+    def inspect = inspect_node(@data, [])
+
+    # Resolves dot access to a setting or namespace; unknown calls use Ruby lookup.
+    # @param name [Symbol] requested setting name.
+    # @param arguments [Array<Object>] arguments supplied by the caller.
+    # @return [Object] resolved setting or namespace.
+    # @raise [NoMethodError] for unknown names or calls with arguments.
+    def method_missing(name, *arguments)
+      return super unless arguments.empty? && @root.respond_to?(name)
+
+      @root.public_send(name)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @root.respond_to?(name) || super
+    end
+
+    private
+
+    def normalize_path(path)
+      case path
+      when String then path.split(".").map!(&:to_sym)
+      when Array then path.map(&:to_sym)
+      else Array(path).map!(&:to_sym)
+      end
+    end
+
+    def inspect_node(data, prefix)
+      body = data.map do |key, value|
+        path = prefix + [key]
+        setting = schema.setting(path)
+        rendered = if setting&.secret?
+                     "[REDACTED]"
+                   elsif value.is_a?(Hash)
+                     inspect_node(value, path)
+                   else
+                     value.inspect
+                   end
+        "#{key}=#{rendered}"
+      end.join(" ")
+      "#<#{self.class.name} #{body}>"
+    end
+  end
+end

data/lib/disposita/error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Disposita
+  # Base class for errors raised by Disposita.
+  #
+  # Consumers may rescue this class when they want one boundary around all
+  # configuration failures, or rescue a narrower subclass to render specific
+  # diagnostics in a CLI or application.
+  class Error < StandardError; end
+
+  # Raised when the consumer declares an invalid schema.
+  class SchemaError < Error; end
+
+  # Base class for failures discovered while validating configuration values.
+  class ValidationError < Error; end
+
+  # Raised when a raw value cannot be converted to its declared schema type.
+  class CoercionError < ValidationError; end
+
+  # Raised when a required setting remains absent after all layers are resolved.
+  class MissingSettingError < ValidationError; end
+
+  # Raised when a source contains a setting not declared by the schema.
+  class UnknownSettingError < ValidationError; end
+
+  # Raised when serialized configuration cannot be decoded safely.
+  class ParseError < Error; end
+
+  # Raised when a source cannot provide its configuration data.
+  class LoadError < Error; end
+
+  # Raised when configuration cannot be persisted to the requested source.
+  class SaveError < Error; end
+
+  # Raised when persisted configuration is newer than the runtime schema.
+  class VersionError < Error; end
+
+  # Raised when a conventional or project path cannot be resolved safely.
+  class PathError < Error; end
+
+  # Raised when secret data would be written to a source that forbids secrets.
+  #
+  # This protects against accidental persistence only. It does not imply that a
+  # source allowing secrets provides encryption or a secret-management system.
+  class UnsafeSecretPersistenceError < SaveError; end
+end