nero 0.5.0 → 0.7.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e28a4b8bcd989c20dd60dc592bfb31039314437b3d8ca5df33b79adefd5cb2e
-  data.tar.gz: f6eb0ec1e9ceb041088a7d2b850494e090f08d98f4e8369f82f0608a4449ab69
+  metadata.gz: 69db9ab0dfd43a40d12a05bd3eb311d12a292a4ba7f1ce0c9f965e908344d659
+  data.tar.gz: 6c29320c5e9f8deafc4c3e207554f59df3e2a97240b73bcc3debefca0a6e3d04
 SHA512:
-  metadata.gz: 98dc2c475e0e164f47d1738dbe32d6dfeeba6b531f6db0b396a25d3e29219c312ac0750206fddea1d9ee450e9205425a5f0342c6b5b13d38867a364e1219bed0
-  data.tar.gz: e9daf1ee287679b10d4ea744c41d3f93bf50570394eb261f7c8b3587a1008efe57b58b7957141aeea48229b65efdaa614f23c181fbf08659a0a878a7a944e773
+  metadata.gz: 5351b2b97b1d49b3a405b5f829d0f716e190a9d9439dd5d54eb8ac673b11efaed1665e352a8973de4a80cde786fda5e0061646d63beafe2626f4fd95d25bf7df
+  data.tar.gz: 3a296f997e83ffd96a508553a638b74abbb0adef2e6487904a4c1be64809f2d5e62cfd7bc98ab0b1ee6e0092cf6888a01359209d540632325542e970102e11f3

data/.envrc

@@ -1 +1,3 @@
-PATH_add bin
+PATH_add bin
+
+source_env_if_exists .envrc.local

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--title 'Nero Documentation'
+--charset utf-8
+--markup markdown
+--no-private
+'lib/**/*.rb' - '*.md'

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 ## [Unreleased]
-...
+
+Total refactor and so quite some breaking changes.
+
+## Breaking Changes
+
+  - Nero.load / Nero.load_file removed — replaced by Nero.parse and Nero.parse_file. These return values directly (or raise Nero::ParseError).
+  - Nero.configure / Nero.configuration removed — custom tags are now registered via a block passed to parse/parse_file/config_for:
+```ruby
+  # Before
+  Nero.configure { |c| c.add_tag("rot/13", klass: RotTag[n: 13]) }
+  Nero.load("secret: !rot/13 uryyb")
+
+  # After
+  Nero.parse("secret: !rot/13 uryyb") { |c| c.add_tag("rot/13", RotTag.new(n: 13)) }
+```
+  - `Nero::Config` removed — results are plain Hashes (string keys) instead of a Config subclass with DigExt/dig!.
+  - `Nero::BaseTag` API changed — tags now implement resolve(args, context:) instead of accessing coder/ctx. Tag options are passed via initialize instead of init_options.
+  - !ref syntax changed — from sequence-based !ref [base, url] to dot-notation !ref base.url.
+  - root: option replaces root:/env: and uses string keys (e.g. root: :development matches the string key "development").
+  - Keys are strings — previously keys were symbolized; now they stay as strings.
+  - !uri and !path tags removed — !uri is gone entirely; !path is no longer a built-in.
+  - `Nero::PathRootTag` renamed to `Nero::RootPathTag` with a new constructor API.
+  - !str/format changed — now also available as !format; the map form (fmt: key) is replaced by a sequence with named-parameter hashes: !format ["http://%<host>s", host: !ref host].
+  - load_config removed (was already deprecated).
+  - Nero::Util removed — deep_symbolize_keys and deep_transform_values are no longer needed.
+  - NERO_ENV_ALL_OPTIONAL env var no longer supported.
+
+## [0.6.0] - 2025-04-10
+
+### deprecations
+
+- `Nero.load_config` - use `Nero.load_file` or `Nero.config_for`.
+
+### other
+
+- API docs live at https://eval.github.io/nero/
+- Config for Rails  
+  The `config.config_dir` is automatically setup, so `Nero.config_for` (formerly `Nero.load_config`) just works.
+- `Nero::Config.dig!` ⛏️💥  
+  Any (Hash-)result from `Nero.load/load_file/config_for` is now an instance of `Nero::Config`.  
+  This class contains `dig!`, a fail-hard variant of `dig`:
+  ```ruby
+  Nero.load(<<~Y).dig!(:smtp_settings, :hose) # 💥 typo
+    smtp_settings:
+      host: 127.0.0.1
+      port: 1025
+  Y
+  #=> 'Nero::DigExt#dig!': path not found [:smtp_settings, :hose] (ArgumentError)
+  ```
 
 ## [0.5.0] - 2025-03-20
 

data/README.md

@@ -37,7 +37,7 @@ production:
 * 💎 declarative YAML-tags for e.g. requiring and coercing env-vars
 * 🛠️ add custom tags
 * 🛤️ `Rails.application.config_for` drop-in
-* ♻️ Zeitwerk-only dependency
+* ♻️ no dependencies
 
 ## Installation
 
@@ -47,6 +47,16 @@ Install the gem and add to the application's Gemfile by executing:
 bundle add nero
 ```
 
+## Configuration
+
+```ruby
+parser = Nero::Parser.new do |config|
+  config.add_tag("str/upcase", ->(args, **) { args.join.upcase })
+end
+parser.parse("hello: !str/upcase world")
+# => #<Nero::Result:0x00000001239f8de0 @errors=[], @value={"hello" => "WORLD"}>
+```
+
 ## Usage
 
 > [!WARNING]  
@@ -56,7 +66,7 @@ bundle add nero
 
 Given the following config:
 ```yaml
-# config/settings.yml
+# config/app.yml
 development:
   # env-var with a fallback
   secret: !env [SECRET, "dummy"]
@@ -73,7 +83,7 @@ Loading this config:
 
 ```ruby
 # Loading development
-Nero.load_config("config/settings", root: :development)
+Nero.parse_file("config/app.yml", root: :development)
 # ...and no ENV-vars were provided
 #=> {secret: "dummy", debug?: false}
 
@@ -81,7 +91,7 @@ Nero.load_config("config/settings", root: :development)
 #=> {secret: "dummy", debug?: true}
 
 # Loading production
-Nero.load_config("config/settings", root: :production)
+Nero.parse_file("config/app.yml", root: :production)
 # ...and no ENV-vars were provided
 # raises error: key not found: "SECRET" (KeyError)
 
@@ -89,15 +99,14 @@ Nero.load_config("config/settings", root: :production)
 #=> {secret: "s3cr3t", max_threads: 3}
 ```
 > [!TIP]  
-> The following configuration would make `Nero.load_config` a drop-in replacement for [Rails.application.config_for](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-config_for):
+> You can also use `Nero.config_for(:app)` (similar to [Rails.application.config_for](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-config_for)).  
+> In Rails applications this gets configured for you. For other application you might need to adjust the `config_dir`:
 ```ruby
-Nero.configure do |config|
-  config.config_dir = Rails.root / "config"
-end
-
-Nero.load_config(:settings, env: Rails.env)
+Nero.config_for(:settings, env: Rails.env)
 ```
 
+[API Documentation](https://eval.github.io/nero/).
+
 ### built-in tags
 
 The following tags are provided:
@@ -169,9 +178,9 @@ $ env NERO_ENV_ALL_OPTIONAL=1 SECRET_KEY_BASE_DUMMY=1 rails asset:precompile
   
   # pass it a map (including a key 'fmt') to use references
   smtp_url: !str/format
-    fmt: smtps://%<user>s:%<pass>s@smtp.gmail.com
-    user: !env SMTP_USER
-    pass: !env SMTP_PASS
+    - smtps://%<user>s:%<pass>s@smtp.gmail.com
+    - user: !env SMTP_USER
+      pass: !env SMTP_PASS
   ```
 - `!ref`  
   Include values from elsewhere:
@@ -189,7 +198,7 @@ $ env NERO_ENV_ALL_OPTIONAL=1 SECRET_KEY_BASE_DUMMY=1 rails asset:precompile
     - !ref[base, url]
 
   # refs are resolved within the tree of the selected root.
-  # The following config won't work when doing `Nero.load_config(:app, root: :prod)`
+  # The following config won't work when doing `Nero.load_file("config/app.yml", root: :prod)`
   dev:
     max_threads: 5
   prod:
@@ -199,13 +208,14 @@ $ env NERO_ENV_ALL_OPTIONAL=1 SECRET_KEY_BASE_DUMMY=1 rails asset:precompile
 
 ### custom tags
 
-Three ways to do this:
+There's three ways to create your own tags.
+
+For all these methods it's helpful to see the API-docs for [Nero::BaseTag](https://eval.github.io/nero/Nero/BaseTag.html).
 
-1. a block  
+1. **a proc**
     ```ruby
     Nero.configure do |nero|
-      nero.add_tag("upcase") do |tag|
-        # `tag` is a `Nero::BaseTag`.
+      nero.add_tag("upcase") do |args, context:|
         # In YAML args are provided as scalar, seq or map:
         # ---
         # k: !upcase bar
@@ -217,42 +227,38 @@ Three ways to do this:
         # k: !upcase
         #   bar: baz
         #
-        # Find these args via `tag.args` (Array or Hash):
-        case tag.args
+        case args
         when Hash
-          tag.args.each_with_object({}) {|(k,v), acc| acc[k] = v.upcase }
+          args.each_with_object({}) {|(k,v), acc| acc[k] = v.upcase }
         else
-          tag.args.map(&:upcase)
+          args.map(&:upcase)
         end
 
-        # NOTE though you might just need one argument, it's helpful to accept a seq nonetheless
-        # as it allows for chaining:
+        # NOTE though a tag might just need one argument (ie scalar),
+        # it's helpful to accept a seq as it allows for chaining:
         # a: !my/inc 4 # scalar suffices
-        # ...but when chaining, it comes as a seq:
-        # a: !my/inc [!my/square 2]
+        # ...but when chaining, it needs to be a seq:
+        # a: !my/inc [ !my/square 2 ]
       end
     end
     ```
-1. re-use existing tag-class  
+    Blocks are passed instances of [Nero::BaseTag](https://eval.github.io/nero/Nero/BaseTag.html).
+1. **re-use existing tag-class**  
    You can add an existing tag under a better fitting name this way.  
    Also: some tag-classes have options that allow for simple customizations (like `coerce` below):
     ```ruby
     Nero.configure do |nero|
-      nero.add_tag("env/upcase", klass: Nero::EnvTag[coerce: :upcase])
-
       # Alias for path/git_root:
-      nero.add_tag("path/project_root", klass: Nero::PathRootTag[containing: '.git'])
+      nero.add_tag("path/project_root", Nero::RootPathTag.new(".git"))
     end
     ```
-1. custom class  
+1. **custom class**  
    ```ruby
    class RotTag < Nero::BaseTag
      # Configure:
      # ```
-     # config.add_tag("rot/12", klass: RotTag[n: 12])
-     # config.add_tag("rot/10", klass: RotTag[n: 10]) do |secret|
-     #   "#{secret} (try breaking this!)"
-     # end
+     # config.add_tag("rot/12", RotTag.new(12))
+     # config.add_tag("rot/10", RotTag.new(10))
      # ```
      #
      # Usage in YAML:
@@ -260,35 +266,52 @@ Three ways to do this:
      # secret: !rot/12 some message
      # very_secret: !rot/10 [ !env [ MSG, some message ] ]
      # ```
-     # => {secret: "EAyq yqEEmsq", very_secret: "Cywo woCCkqo (try breaking this!)"}
-   
-     # By overriding `init_options` we can restrict/require options,
-     # provide default values and do any other setup.  
-     # By default an option is available via `options[:foo]`.
-     def init_options(n: 10)
-       super # no specific assignments, so available via `options[:n]`.
-     end
+     # => {secret: "EAyq yqEEmsq", very_secret: "Cywo woCCkqo)"}
 
      def chars
        @chars ||= (('a'..'z').to_a + ('A'..'Z').to_a + ('0'..'9').to_a)
      end
 
-     def resolve(**) # currently no keywords are passed, but `**` allows for future ones.
+     def resolve(args, context:)
        # Here we actually do the work: get the args, rotate strings and delegate to the block.
        # `args` are the resolved nested args (so e.g. `!env MSG` is already resolved).
-       # `config` is the tag's config, and contains e.g. the block.
-       block = config.fetch(:block, :itself.to_proc)
        # String#tr replaces any character from the first collection with the same position in the other:
-       args.join.tr(chars.join, chars.rotate(options[:n]).join).then(&block)
+       args.join.tr(chars.join, chars.rotate(@n).join)
      end
    end
    ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+# Setup
+bin/setup  # Make sure it exits with code 0
+
+# Run tests
+rake
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Using [mise](https://mise.jdx.dev/) for env-vars is recommended.
+
+### Releasing
+
+1. Update `lib/bonchi/version.rb`
+   ```
+   bin/rake 'gem:write_version[0.5.0]'
+   # commit&push
+   # check CI
+   ```
+1. Tag
+   ```
+   gem_push=no bin/rake release
+   ```
+1. Release workflow from GitHub Actions...
+   - ...publishes to RubyGems (with Sigstore attestation)
+   - ...creates git GitHub release after successful publish
+1. Update `version.rb` for next dev-cycle
+   ```
+   bin/rake 'gem:write_version[0.6.0.dev]'
+   ```
 
 ## Contributing
 

data/lib/nero/base_tag.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Nero
+  class BaseTag
+    def resolve(args, context:)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/nero/context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Nero
+  class Context
+    attr_reader :errors, :environ, :dir
+
+    def initialize(environ:, errors:, dir: nil)
+      @environ = environ
+      @errors = errors
+      @dir = dir || File.realpath(".")
+    end
+
+    def add_error(message)
+      @errors << Error.new(message)
+    end
+  end
+end

data/lib/nero/deferred.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Nero
+  class Deferred
+    attr_reader :tag, :args
+
+    def initialize(tag, args) = (@tag, @args = tag, args)
+  end
+end

data/lib/nero/env_tag.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Nero
+  class EnvTag < BaseTag
+    def initialize(coerce: nil, optional: false)
+      @coerce = coerce
+      @optional = optional
+    end
+
+    def resolve(args, context:)
+      var_name = args[0]
+      default = args[1]
+      raw = context.environ[var_name]
+
+      if raw.nil? && default.nil?
+        context.add_error("environment variable #{var_name} is not set") unless @optional
+        return nil
+      end
+
+      value = raw || default.to_s
+
+      return value unless @coerce
+
+      begin
+        @coerce.call(value)
+      rescue ArgumentError => e
+        context.add_error("cannot coerce #{var_name}=#{value.inspect}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/nero/error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Nero
+  class Error
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+    end
+
+    def to_s = message
+  end
+
+  class ParseError < StandardError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super(errors.map(&:message).join(", "))
+    end
+  end
+end

data/lib/nero/format_tag.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Nero
+  class FormatTag < BaseTag
+    def resolve(args, context:)
+      template = args[0]
+      opts = args.each_with_object({}) do |arg, h|
+        h.merge!(arg.transform_keys(&:to_sym)) if arg.is_a?(Hash)
+      end
+      format(template, opts)
+    rescue KeyError => e
+      context.add_error("format error: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/nero/parser.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Nero
+  class Parser
+    TO_INT = ->(v) { Integer(v) }
+    TO_FLOAT = ->(v) { Float(v) }
+    TO_BOOL = ->(v) { !%w[0 false no off].include?(v.downcase) }
+    TO_PATH = ->(v) { Pathname.new(v) }
+
+    def initialize(environ: ENV, root: nil, &block)
+      @environ = environ
+      @root = root&.to_s
+      @tags = {}
+      add_tag("env", EnvTag.new)
+      add_tag("env?", EnvTag.new(optional: true))
+      add_tag("env/int", EnvTag.new(coerce: TO_INT))
+      add_tag("env/int?", EnvTag.new(coerce: TO_INT, optional: true))
+      add_tag("env/integer", EnvTag.new(coerce: TO_INT))
+      add_tag("env/integer?", EnvTag.new(coerce: TO_INT, optional: true))
+      add_tag("env/bool", EnvTag.new(coerce: TO_BOOL))
+      add_tag("env/bool?", EnvTag.new(coerce: TO_BOOL, optional: true))
+      add_tag("env/boolean", EnvTag.new(coerce: TO_BOOL))
+      add_tag("env/boolean?", EnvTag.new(coerce: TO_BOOL, optional: true))
+      add_tag("env/float", EnvTag.new(coerce: TO_FLOAT))
+      add_tag("env/float?", EnvTag.new(coerce: TO_FLOAT, optional: true))
+      add_tag("env/path", EnvTag.new(coerce: TO_PATH))
+      add_tag("env/path?", EnvTag.new(coerce: TO_PATH, optional: true))
+      add_tag("str/format", FormatTag.new)
+      add_tag("format", FormatTag.new)
+      add_tag("ref", RefTag.new)
+      block&.call(self)
+    end
+
+    def add_tag(name, handler)
+      @tags[name] = handler.is_a?(Proc) ? ProcTag.new(handler) : handler
+    end
+
+    def parse(yaml, dir: nil)
+      errors = []
+      tree = ::Psych.parse_stream(yaml)
+      ctx = Context.new(environ: @environ, errors: errors, dir: dir)
+
+      if @root
+        mark_inactive_roots(tree)
+      end
+
+      visitor = Visitor.build(@tags, ctx)
+      result = visitor.accept(tree)
+      value = result.first
+
+      if @root
+        unless value.is_a?(Hash) && value.key?(@root)
+          ctx.add_error("root #{@root.inspect} not found in top-level keys")
+          return Result.new(nil, errors.freeze)
+        end
+        value = value[@root]
+      end
+
+      value = resolve_refs(value, value, ctx) if contains_ref?(value)
+      Result.new(value, errors.freeze)
+    end
+
+    def parse_file(path)
+      dir = File.dirname(File.realpath(path))
+      parse(File.read(path), dir: dir)
+    end
+
+    private
+
+    def mark_inactive_roots(tree)
+      doc = tree.children.first
+      mapping = doc&.root
+      return unless mapping.is_a?(::Psych::Nodes::Mapping)
+
+      root_node = mapping.children.each_slice(2).find { |k, _| k.value == @root }&.last
+      used_anchors = root_node ? collect_aliases(root_node) : Set.new
+
+      mapping.children.each_slice(2) do |key_node, val_node|
+        next if key_node.value == @root
+        next if used_anchors.include?(val_node.anchor)
+
+        strip_custom_tags(val_node)
+      end
+    end
+
+    def collect_aliases(node, result = Set.new)
+      if node.is_a?(::Psych::Nodes::Alias)
+        result << node.anchor
+      elsif node.respond_to?(:children) && node.children
+        node.children.each { |child| collect_aliases(child, result) }
+      end
+      result
+    end
+
+    def strip_custom_tags(node)
+      case node
+      when ::Psych::Nodes::Scalar, ::Psych::Nodes::Sequence, ::Psych::Nodes::Mapping
+        node.tag = nil if node.tag&.start_with?("!")
+      end
+      return unless node.respond_to?(:children) && node.children
+      node.children.each { |child| strip_custom_tags(child) }
+    end
+
+    def contains_ref?(value)
+      case value
+      when Ref, Deferred then true
+      when Hash then value.values.any? { |v| contains_ref?(v) }
+      when Array then value.any? { |v| contains_ref?(v) }
+      else false
+      end
+    end
+
+    def resolve_refs(value, root, ctx, visited = Set.new)
+      case value
+      when Ref
+        key = value.path.join(".")
+        if visited.include?(key)
+          ctx.add_error("circular reference: #{key}")
+          return nil
+        end
+        target = value.path.reduce(root) { |h, k| h.is_a?(Hash) ? h[k] : nil }
+        if target.nil?
+          ctx.add_error("unknown ref #{key}")
+          return nil
+        end
+        resolve_refs(target, root, ctx, visited | [key])
+      when Deferred
+        resolved_args = resolve_refs(value.args, root, ctx, visited)
+        value.tag.resolve(resolved_args, context: ctx)
+      when Hash
+        value.transform_values { |v| resolve_refs(v, root, ctx, visited) }
+      when Array
+        value.map { |v| resolve_refs(v, root, ctx, visited) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/nero/proc_tag.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Nero
+  class ProcTag < BaseTag
+    def initialize(callable) = @callable = callable
+
+    def resolve(args, context:) = @callable.call(args, context:)
+  end
+end

data/lib/nero/rails/credentials_tag.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Nero
+  module Rails
+    class CredentialsTag < BaseTag
+      attr_reader :credentials
+
+      # TODO lookup?
+      def initialize(credentials)
+        @credentials = credentials
+      end
+
+      def resolve(args, context:)
+        keys = args.map(&:to_sym)
+        #value = ::Rails.application.credentials.dig(*keys)
+        value = credentials.dig(*keys)
+        return value if value
+
+        context.add_error("credential #{args.join(".")} not found")
+        nil
+      end
+    end
+  end
+end

data/lib/nero/rails/duration_tag.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Nero
+  module Rails
+    class DurationTag < BaseTag
+      UNITS = %w[seconds minutes hours days weeks months years].freeze
+
+      def resolve(args, context:)
+        amount = args[0]
+        unit = args[1]&.to_s
+
+        unless amount.is_a?(Numeric)
+          context.add_error("duration requires a numeric amount, got #{amount.inspect}")
+          return nil
+        end
+
+        unless UNITS.include?(unit)
+          context.add_error("duration unknown unit #{unit.inspect}, expected one of: #{UNITS.join(", ")}")
+          return nil
+        end
+
+        amount.public_send(unit)
+      end
+    end
+  end
+end

data/lib/nero/rails/string_inquirer_tag.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Nero
+  module Rails
+    class StringInquirerTag < BaseTag
+      def resolve(args, context:)
+        value = args[0]&.to_s
+        if value.nil? || value.empty?
+          context.add_error("str/inquirer requires a non-empty string argument")
+          return nil
+        end
+        ActiveSupport::StringInquirer.new(value)
+      end
+    end
+  end
+end