myway_config 0.1.1

data/docs/api/loaders.md

@@ -0,0 +1,296 @@
+# Loaders
+
+MywayConfig provides custom loaders that extend Anyway Config's loading system.
+
+## Loading Priority
+
+Configuration values are loaded in order (lowest to highest priority):
+
+1. **DefaultsLoader** - Bundled defaults from your gem
+2. **XdgConfigLoader** - User's XDG config files
+3. **Anyway Config loaders** - Project config, local overrides
+4. **Environment variables** - `PREFIX_KEY=value`
+5. **Constructor overrides** - Hash passed to `new`
+
+Higher priority sources override lower priority values.
+
+---
+
+## DefaultsLoader
+
+Loads bundled default configuration from a YAML file.
+
+### Purpose
+
+Ensures default values are always available regardless of where the gem is installed. The defaults file is the single source of truth for configuration structure.
+
+### Registration
+
+```ruby
+class MyApp::Config < MywayConfig::Base
+  config_name :myapp
+  defaults_path File.expand_path("config/defaults.yml", __dir__)
+end
+```
+
+### Class Methods
+
+#### register
+
+Register a defaults file path.
+
+```ruby
+MywayConfig::Loaders::DefaultsLoader.register(:myapp, "/path/to/defaults.yml")
+```
+
+---
+
+#### defaults_path
+
+Get the registered path for a config name.
+
+```ruby
+MywayConfig::Loaders::DefaultsLoader.defaults_path(:myapp)
+# => "/path/to/defaults.yml"
+```
+
+---
+
+#### defaults_exist?
+
+Check if defaults file exists.
+
+```ruby
+MywayConfig::Loaders::DefaultsLoader.defaults_exist?(:myapp)
+# => true
+```
+
+---
+
+#### schema
+
+Get the defaults section from the YAML file.
+
+```ruby
+MywayConfig::Loaders::DefaultsLoader.schema(:myapp)
+# => {database: {host: "localhost", ...}, log_level: :info, ...}
+```
+
+---
+
+#### valid_environments
+
+Get list of valid environment names.
+
+```ruby
+MywayConfig::Loaders::DefaultsLoader.valid_environments(:myapp)
+# => [:development, :production, :test]
+```
+
+---
+
+#### valid_environment?
+
+Check if an environment name is valid.
+
+```ruby
+MywayConfig::Loaders::DefaultsLoader.valid_environment?(:myapp, :production)
+# => true
+
+MywayConfig::Loaders::DefaultsLoader.valid_environment?(:myapp, :staging)
+# => false
+```
+
+---
+
+### Loading Behavior
+
+The loader:
+
+1. Reads the `defaults:` section as base values
+2. Deep-merges current environment's overrides
+3. Returns the merged configuration
+
+```yaml
+# defaults.yml
+defaults:
+  database:
+    host: localhost
+    port: 5432
+
+production:
+  database:
+    host: prod-db.example.com
+```
+
+In production, the loader returns:
+
+```ruby
+{database: {host: "prod-db.example.com", port: 5432}}
+```
+
+---
+
+## XdgConfigLoader
+
+Loads user configuration from XDG Base Directory paths.
+
+### Purpose
+
+Allows users to override configuration globally without modifying project files. Useful for personal preferences or machine-specific settings.
+
+### XDG Paths
+
+The loader checks these paths (in order of priority):
+
+1. **macOS only:** `~/Library/Application Support/{app}/{app}.yml`
+2. `~/.config/{app}/{app}.yml` (XDG default)
+3. `$XDG_CONFIG_HOME/{app}/{app}.yml` (if set)
+
+Higher-numbered paths take precedence.
+
+### Class Methods
+
+#### config_paths
+
+Get all potential config directory paths.
+
+```ruby
+MywayConfig::Loaders::XdgConfigLoader.config_paths(:myapp)
+# => [
+#      "/Users/me/Library/Application Support/myapp",  # macOS only
+#      "/Users/me/.config/myapp"
+#    ]
+```
+
+---
+
+#### find_config_file
+
+Find the first existing config file.
+
+```ruby
+MywayConfig::Loaders::XdgConfigLoader.find_config_file(:myapp)
+# => "/Users/me/.config/myapp/myapp.yml" or nil
+```
+
+---
+
+### File Format
+
+XDG config files can be flat or environment-specific:
+
+**Flat format:**
+
+```yaml
+# ~/.config/myapp/myapp.yml
+database:
+  host: my-custom-host
+  port: 5433
+```
+
+**With environments:**
+
+```yaml
+# ~/.config/myapp/myapp.yml
+development:
+  database:
+    host: dev-custom-host
+
+production:
+  database:
+    host: prod-custom-host
+```
+
+### Example Usage
+
+Create a user-specific override:
+
+```bash
+mkdir -p ~/.config/myapp
+cat > ~/.config/myapp/myapp.yml << 'EOF'
+database:
+  host: custom-db.local
+  port: 5433
+EOF
+```
+
+Now your application uses these values:
+
+```ruby
+config = MyApp::Config.new
+config.database.host  # => "custom-db.local"
+config.database.port  # => 5433
+```
+
+---
+
+## Loader Registration
+
+Loaders are automatically registered when you call `MywayConfig.setup!` (which happens when requiring the gem).
+
+```ruby
+# lib/myway_config.rb
+module MywayConfig
+  def self.setup!
+    return if @setup_complete
+
+    Anyway.loaders.insert_before(
+      :yml,
+      :xdg_config,
+      Loaders::XdgConfigLoader
+    )
+
+    Anyway.loaders.insert_before(
+      :xdg_config,
+      :bundled_defaults,
+      Loaders::DefaultsLoader
+    )
+
+    @setup_complete = true
+  end
+end
+```
+
+### Manual Setup
+
+If you need to control when loaders are registered:
+
+```ruby
+require 'myway_config'
+
+# Check if already set up
+MywayConfig.setup?  # => true (automatic)
+
+# Reset and re-setup (mainly for testing)
+MywayConfig.reset!
+MywayConfig.setup!
+```
+
+---
+
+## Custom Loaders
+
+You can create custom loaders by extending `Anyway::Loaders::Base`:
+
+```ruby
+class MyCustomLoader < Anyway::Loaders::Base
+  def call(name:, **options)
+    trace!(:custom, source: "my_source") do
+      # Return a Hash of configuration values
+      load_from_custom_source(name)
+    end
+  end
+
+  private
+
+  def load_from_custom_source(name)
+    # Your loading logic here
+    {}
+  end
+end
+
+# Register the loader
+Anyway.loaders.insert_after(:yml, :custom, MyCustomLoader)
+```
+

data/docs/development/contributing.md

@@ -0,0 +1,215 @@
+# Contributing
+
+Thank you for your interest in contributing to MywayConfig!
+
+## Getting Started
+
+### Prerequisites
+
+- Ruby 3.2 or later
+- Git
+- Bundler
+
+### Setup
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/YOUR_USERNAME/myway_config.git
+cd myway_config
+
+# Install dependencies
+bin/setup
+
+# Verify everything works
+bundle exec rake test
+```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Make Changes
+
+- Write code following the existing style
+- Add tests for new functionality
+- Update documentation if needed
+
+### 3. Run Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run a specific test file
+bundle exec ruby -Itest test/test_myway_config.rb
+
+# Run a specific test
+bundle exec ruby -Itest test/test_myway_config.rb -n test_auto_configure
+```
+
+### 4. Check Coverage
+
+```bash
+# Run tests with coverage
+bundle exec rake test
+
+# Coverage report is displayed after tests complete
+```
+
+The project uses `single_cov` for line-level coverage. All lines should be covered.
+
+### 5. Commit Changes
+
+```bash
+git add .
+git commit -m "Add feature: description of changes"
+```
+
+### 6. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a Pull Request on GitHub.
+
+## Code Style
+
+### Ruby Style
+
+- Use 2 spaces for indentation
+- Use `frozen_string_literal: true` pragma
+- Prefer `do...end` for multi-line blocks
+- Prefer `{ }` for single-line blocks
+
+### Documentation
+
+- Add YARD documentation for public methods
+- Update guides for user-facing changes
+- Include examples in documentation
+
+### Testing
+
+- Write tests for all new code
+- Test edge cases and error conditions
+- Use descriptive test names
+
+## Project Structure
+
+```
+lib/
+├── myway_config.rb              # Entry point
+└── myway_config/
+    ├── base.rb                  # Configuration base class
+    ├── config_section.rb        # Hash-like wrapper
+    ├── version.rb               # Version number
+    └── loaders/
+        ├── defaults_loader.rb   # Bundled defaults
+        └── xdg_config_loader.rb # XDG paths
+```
+
+## Adding Features
+
+### New Configuration Option
+
+1. Add to `defaults.yml` if applicable
+2. Add accessor method if needed
+3. Add tests
+4. Update documentation
+
+### New Loader
+
+1. Create loader in `lib/myway_config/loaders/`
+2. Extend `Anyway::Loaders::Base`
+3. Register in `MywayConfig.setup!`
+4. Add tests
+5. Document in `docs/api/loaders.md`
+
+### New ConfigSection Method
+
+1. Add method to `config_section.rb`
+2. Add YARD documentation
+3. Add tests
+4. Update `docs/api/config-section.md`
+
+## Running the Demo
+
+```bash
+# Run the demo application
+ruby examples/xyzzy.rb
+
+# With different environments
+RACK_ENV=production ruby examples/xyzzy.rb
+RACK_ENV=test ruby examples/xyzzy.rb
+
+# With environment variable overrides
+XYZZY_DATABASE__HOST=custom-db.local ruby examples/xyzzy.rb
+```
+
+## Interactive Console
+
+```bash
+# Start IRB with the gem loaded
+bin/console
+
+# Or from the examples directory
+cd examples
+irb -r ./xyzzy.rb
+```
+
+## Documentation
+
+Documentation is built with MkDocs and Material theme.
+
+### Preview Documentation
+
+```bash
+# Install MkDocs (if not installed)
+pip install mkdocs mkdocs-material
+
+# Serve documentation locally
+mkdocs serve
+
+# Build static site
+mkdocs build
+```
+
+### Documentation Structure
+
+```
+docs/
+├── index.md                 # Home page
+├── getting-started/         # Installation and quick start
+├── guides/                  # Usage guides
+├── examples/                # Real-world examples
+├── api/                     # API reference
+└── development/             # Contributing info
+```
+
+## Releasing
+
+Releases are managed by maintainers:
+
+1. Update `lib/myway_config/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit: `git commit -m "Release vX.Y.Z"`
+4. Tag: `git tag vX.Y.Z`
+5. Push: `git push origin main --tags`
+6. Build and publish: `gem build && gem push myway_config-X.Y.Z.gem`
+
+## Getting Help
+
+- Open an issue for bugs or feature requests
+- Check existing issues before creating new ones
+- Provide reproduction steps for bugs
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+

data/docs/development/index.md

@@ -0,0 +1,100 @@
+# Development
+
+Information for contributing to MywayConfig.
+
+## Guides
+
+### [Contributing](contributing.md)
+
+How to contribute to the project:
+
+- Setting up the development environment
+- Making changes
+- Submitting pull requests
+
+### [Testing](testing.md)
+
+Running and writing tests:
+
+- Test suite overview
+- Running tests
+- Code coverage
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/madbomber/myway_config.git
+cd myway_config
+
+# Install dependencies
+bin/setup
+
+# Run tests
+bundle exec rake test
+
+# Start interactive console
+bin/console
+```
+
+## Project Structure
+
+```
+myway_config/
+├── lib/
+│   ├── myway_config.rb          # Main module and setup
+│   └── myway_config/
+│       ├── base.rb              # Base configuration class
+│       ├── config_section.rb    # Hash-like wrapper
+│       ├── version.rb           # Version constant
+│       └── loaders/
+│           ├── defaults_loader.rb     # Bundled defaults loader
+│           └── xdg_config_loader.rb   # XDG config loader
+├── test/
+│   ├── test_helper.rb           # Test setup
+│   ├── test_myway_config.rb     # Main tests
+│   └── fixtures/                # Test YAML files
+├── examples/
+│   ├── xyzzy.rb                 # Demo application
+│   └── config/
+│       └── defaults.yml         # Demo defaults
+├── docs/                        # MkDocs documentation
+└── .github/
+    └── workflows/
+        └── ci.yml               # GitHub Actions CI
+```
+
+## Architecture
+
+MywayConfig extends [Anyway Config](https://github.com/palkan/anyway_config) with:
+
+1. **DefaultsLoader** - Loads bundled YAML defaults
+2. **XdgConfigLoader** - Loads user XDG config files
+3. **ConfigSection** - Hash-like wrapper with Enumerable
+4. **Base** - Configuration base class with `auto_configure!`
+
+### Loading Order
+
+```
+DefaultsLoader (lowest priority)
+    ↓
+XdgConfigLoader
+    ↓
+Anyway Config loaders (yml, local)
+    ↓
+Environment variables
+    ↓
+Constructor overrides (highest priority)
+```
+
+## Dependencies
+
+- Ruby 3.2+
+- anyway_config (~> 2.0)
+
+### Development Dependencies
+
+- minitest
+- rake
+- single_cov
+