decoding 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3b7725a14c0738d4860f46509eb8e2ce781f6298bb9253797c0dad84f769564
-  data.tar.gz: '07785a90e96fe8a56bcbb2986d0cdd61aca6e75541f084e1a5c7be5799261912'
+  metadata.gz: b61483d249ba9fc5939de6d7b1aadf7ecc6c2ea4fceb65f927447a4d3828bcfa
+  data.tar.gz: beab3f51cec564c1bdf2bd7f40ffbc4f97280e7197e14b9e8cd5a980b3756366
 SHA512:
-  metadata.gz: 4c253b152f0f82f95fb3a5a77c84acf741686c776492418967b5a9ca11800f1296351af373126f9d1efaeba8dd2418d3bbbdbdc1ad88e77c314489442b9af1a6
-  data.tar.gz: ddba1656e7e7cec32423d0c1e6ada7494972b620666e1dc3daa70b7bf5c1210a0ad50911778b74e8c06d2f4befbe3f644c44bf38b05c8b97a266fdf3d0afd49f
+  metadata.gz: fcc99943040df23b080b84d32b0a6e8755dd2fd19c4a62befdd49970c843f0e28d96c1df885bb7c42538cc2e2b65f89d71c9ebb4f0f1da983d726bc95de39002
+  data.tar.gz: 8e53f19908fbccadb6068b851d96188d583267787631ce0c6207d61d2e2542716f44012c7ce0996b1146026ec07a764ad716c6b15d1b1c09974d3bf0994057d0

data/.claude/hooks/allow-rspec.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Auto-allow RSpec commands
+
+# Read JSON from stdin
+input=$(cat)
+
+# Extract command from JSON (handle mcp__acp__Bash tool)
+command=$(echo "$input" | grep -o '"command":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+# Check if it's an RSpec command
+if [[ "$command" =~ (^|[[:space:]])bundle[[:space:]]+exec[[:space:]]+rspec || "$command" =~ (^|[[:space:]])rspec ]]; then
+  # Auto-allow RSpec commands
+  echo '{"permissionDecision":"allow","permissionDecisionReason":"RSpec commands are safe in this repo"}' >&2
+  exit 0
+fi
+
+# For other commands, no special handling
+exit 0

data/.claude/settings.json

@@ -0,0 +1,39 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__acp__Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/allow-rspec.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '## Current Git Branch' && git branch --show-current && echo '\n## Pending Changes' && git status --short",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__acp__Edit|mcp__acp__Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bundle exec rubocop -a \"$CLAUDE_TOOL_RESULT_file_path\" 2>&1 || true",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

data/.rubocop.yml

@@ -23,6 +23,9 @@ Metrics/ModuleLength:
   Exclude:
     - spec/**/*_spec.rb
 
+Metrics/AbcSize:
+  Max: 18
+
 Metrics/BlockLength:
   Exclude:
     - spec/**/*_spec.rb

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.2.4]
+
+* Make `succeed` and `fail` proper, composable decoders
+* Ensure different decoders use the same error values
+* Turn exceptions in decoder blocks into errors
+* Use immutable failure values as errors
+
+## [0.2.3] - 2025-10-25
+
+* Implement `Decoding::Result#deconstruct` to support pattern matching on result values.
+
 ## [0.2.2] - 2025-10-25
 
 * Added `Result#unwrap_err`

data/CLAUDE.md

@@ -0,0 +1,79 @@
+# Decoding Gem - Instructions for Agentic Coding
+
+## Project Overview
+
+Ruby gem for decoding dynamic/external data into known structures. Functional-style decoder composition pattern. Min Ruby 3.3.
+
+## Code Style & Standards
+
+**Must follow:**
+- Rubocop with rubocop-rspec, rubocop-performance, rubocop-rake
+- Double quotes for strings
+- Max line length: 140
+- Frozen string literals
+- Run `rake` (runs specs, rubocop, yard)
+
+**Testing:**
+- RSpec with SimpleCov
+- Min coverage: 100% line, 100% branch
+- Test file: `spec/<module>/<class>_spec.rb`
+- Run with `COVERAGE=true bundle exec rspec`
+
+## Architecture
+
+**Core concepts:**
+- Decoders are callables (`decoder.call(value)` → `Result`)
+- `Result` has `Ok` and `Err` subclasses
+- Immutable `Failure` class for error tracking
+- Decoder composition via `map`, `and_then`, `any`
+- Module `Decoding::Decoders` contains all decoders
+
+**Key files:**
+- `lib/decoding/decoder.rb` - decoder protocol
+- `lib/decoding/result.rb` - result type
+- `lib/decoding/failure.rb` - error tracking
+- `lib/decoding/decoders.rb` - all decoder implementations
+- `lib/decoding/decoders/*.rb` - individual decoders
+
+## Common Tasks
+
+**Add new decoder:**
+1. Create `lib/decoding/decoders/<name>.rb` with callable returning Result
+2. Add to `Decoders` module in `lib/decoding/decoders.rb`
+3. Add spec in `spec/decoding/decoders/<name>_spec.rb`
+4. Test success/failure cases
+5. Run `rake` to verify
+
+**Modify existing decoder:**
+1. Read current implementation and spec first
+2. Keep backward compatibility unless breaking change justified
+3. Update specs for new behavior
+4. Verify coverage remains at 100%
+
+**Run tests:**
+- All: `COVERAGE=true bundle exec rspec`
+- Single file: `bundle exec rspec spec/path/to/spec.rb`
+- CI tests Ruby 3.3, 3.4, 4.0
+
+**Code quality:**
+- Run `bundle exec rubocop` (auto-fix: `-a` or `-A`)
+- Generate docs: `bundle exec yard`
+- Check docs: `bundle exec yard server`
+
+## Guidelines
+
+- Decoders compose via functional patterns, avoid mutation
+- Error messages should be descriptive
+- Use `frozen_string_literal: true`
+- Follow existing patterns in `lib/decoding/decoders/*.rb`
+- Keep `Failure` immutable
+- YARD docs for public methods
+- Test edge cases (nil, empty, wrong types)
+
+## Don't
+
+- Break immutability of Result/Failure
+- Add dependencies without justification
+- Skip specs for new decoders
+- Ignore Rubocop violations
+- Add features without tests

data/lib/decoding/decoders/and_then.rb

@@ -24,6 +24,8 @@ module Decoding
         @decoder.call(value).and_then do |decoded_value|
           @block.call(decoded_value).call(value)
         end
+      rescue StandardError => e
+        err(failure("error in and_then block: #{e.message}"))
       end
     end
   end

data/lib/decoding/decoders/array.rb

@@ -24,7 +24,7 @@ module Decoding
             .map { |v, i| @decoder.call(v).map_err { _1.push(i) } }
             .then { all _1 }
         else
-          err("expected an Array, got: #{value.class}")
+          err(failure("expected an Array, got: #{value.class}"))
         end
       end
     end

data/lib/decoding/decoders/at.rb

@@ -17,7 +17,7 @@ module Decoding
       end
 
       # @param value [Object]
-      # @return [Deceoding::Result<a>]
+      # @return [Decoding::Result<a>]
       def call(value)
         first, *rest = @keys.reverse
         nested_decoder = rest.reduce(Decoders::Field.new(first, @decoder)) do |acc, k|

data/lib/decoding/decoders/fail.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # A decoder that always fails with a predetermined error message, ignoring
+    # any input. This is useful for signaling errors in conditional decoder
+    # composition, such as inside {Decoders::AndThen}.
+    #
+    # @example Always fail with a message
+    #   decode(Fail.new("unsupported"), "anything")
+    #   # => Decoding::Err("unsupported")
+    #
+    # @example Use in conditional decoding
+    #   and_then(field("version", integer)) do |version|
+    #     case version
+    #     when 1 then field("name", string)
+    #     else Fail.new("unsupported version: #{version}")
+    #     end
+    #   end
+    class Fail < Decoder
+      # @param message [String] the error message to always return
+      def initialize(message)
+        @message = message
+        super()
+      end
+
+      # @param _value [Object] ignored input
+      # @return [Decoding::Result<Object>]
+      def call(_value) = err(failure(@message))
+    end
+  end
+end

data/lib/decoding/decoders/field.rb

@@ -11,13 +11,13 @@ module Decoding
       # @param key [Object]
       # @param decoder [Decoding::Decoder<a>]
       def initialize(key, decoder)
-        @key = key.to_str
+        @key = String(key)
         @decoder = decoder.to_decoder
         super()
       end
 
       # @param value [Object]
-      # @return [Deceoding::Result<a>]
+      # @return [Decoding::Result<a>]
       def call(value)
         if value.is_a?(::Hash)
           if value.key?(@key)

data/lib/decoding/decoders/hash.rb

@@ -19,24 +19,22 @@ module Decoding
       # @param value [Object]
       # @return [Decoding::Result<Hash<a, b>>]
       def call(value)
-        if value.is_a?(::Hash)
-          key_value_pairs = value.map do |k, v|
-            all(
-              [
-                @key_decoder
-                  .call(k)
-                  .map_err { |e| failure("error decoding key #{k.inspect}: #{e}") },
+        return err(failure("expected Hash, got #{value.class}")) unless value.is_a?(::Hash)
 
-                @value_decoder
-                  .call(v)
-                  .map_err { |e| failure("error decoding value for key #{k.inspect}: #{e}") }
-              ]
-            )
-          end
-          all(key_value_pairs).map(&:to_h)
-        else
-          err("expected Hash, got #{value.class}")
+        key_value_pairs = value.map do |k, v|
+          all(
+            [
+              @key_decoder
+                .call(k)
+                .map_err { |e| failure("error decoding key #{k.inspect}: #{e}") },
+
+              @value_decoder
+                .call(v)
+                .map_err { |e| failure("error decoding value for key #{k.inspect}: #{e}") }
+            ]
+          )
         end
+        all(key_value_pairs).map(&:to_h)
       end
     end
   end

data/lib/decoding/decoders/index.rb

@@ -23,13 +23,13 @@ module Decoding
       # @param value [Object]
       # @return [Decoding::Decoder<Object>]
       def call(value)
-        return err("expected an Array, got: #{value.class}") unless value.is_a?(::Array)
+        return err(failure("expected an Array, got: #{value.class}")) unless value.is_a?(::Array)
 
         @decoder
           .call(value.fetch(@index))
-          .map_err { "error decoding array item #{@index}: #{_1}" }
+          .map_err { _1.push(@index) }
       rescue IndexError => e
-        err("error decoding array: #{e}")
+        err(failure("error decoding array: #{e}"))
       end
     end
   end

data/lib/decoding/decoders/map.rb

@@ -24,6 +24,8 @@ module Decoding
         Result
           .all(@decoders.map { _1.call(value) })
           .map { @block.call(*_1) }
+      rescue StandardError => e
+        err(failure("error in map block: #{e.message}"))
       end
     end
   end

data/lib/decoding/decoders/pass.rb

@@ -5,7 +5,7 @@ module Decoding
     # Decoder that returns the original value as-is. You are not likely to need
     # this that often, as it kind of defeats the point of decoding -- but it
     # might be useful to inspect the original input value for logging or
-    # debguging purposes.
+    # debugging purposes.
     class Pass < Decoder
       def call(value) = ok(value)
     end

data/lib/decoding/decoders/succeed.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # A decoder that always succeeds with a predetermined value, ignoring any
+    # input. This is useful for providing default values or as a building block
+    # in decoder composition.
+    #
+    # @example Always return a fixed value
+    #   decode(Succeed.new(5), "anything") # => Decoding::Ok(5)
+    #
+    # @example Use with field to provide defaults
+    #   decode(any(field("x", integer), Succeed.new(0)), {})
+    #   # => Decoding::Ok(0)
+    class Succeed < Decoder
+      # @param value [Object] the value to always return
+      def initialize(value)
+        @value = value
+        super()
+      end
+
+      # @param _value [Object] ignored input
+      # @return [Decoding::Result<Object>]
+      def call(_value) = ok(@value)
+    end
+  end
+end

data/lib/decoding/decoders.rb

@@ -10,6 +10,8 @@ require_relative "decoders/hash"
 require_relative "decoders/and_then"
 require_relative "decoders/at"
 require_relative "decoders/pass"
+require_relative "decoders/succeed"
+require_relative "decoders/fail"
 require_relative "result"
 
 module Decoding
@@ -30,7 +32,7 @@ module Decoding
 
     # Decode any string value that matches a regular expression.
     #
-    # @param re [Regexp, String]
+    # @param regex [Regexp, String]
     # @return [Decoding::Decoder<String>]
     # @see Decoding::Decoders::Match
     def regexp(regex) = Decoders::Match.new(Regexp.new(regex))
@@ -106,14 +108,14 @@ module Decoding
     # @example
     #   decode(succeed(5), "foo") # => Decoding::Ok(5)
     # @return [Decoding::Decoder<String>]
-    def succeed(value) = ->(_) { Result.ok(value) }
+    def succeed(value) = Decoders::Succeed.new(value)
 
     # A decoder that always fails with the given value.
     #
     # @example
     #   decode(fail("oh no"), "foo") # => Decoding::Err("oh no")
     # @return [Decoding::Decoder<String>]
-    def fail(value) = ->(_) { Result.err(Decoding::Failure.new(value)) }
+    def fail(value) = Decoders::Fail.new(value)
 
     # A decoder that returns the input value, unaltered.
     #

data/lib/decoding/failure.rb

@@ -9,10 +9,12 @@ module Decoding
   # error, the `array` decoder can push `3` to the stack to indicate that
   # happened at index 3 in its input value.
   class Failure
-    # @paramn msg [String]
-    def initialize(msg)
+    # @param msg [String]
+    # @param path [Array] Internal parameter for creating copies with updated paths
+    def initialize(msg, path = [])
       @msg = msg
-      @path = []
+      @path = path.dup.freeze
+      freeze
     end
 
     def eql?(other)
@@ -23,12 +25,12 @@ module Decoding
     alias == eql?
 
     # Add segments to the stack of errors.
+    # Returns a new Failure instance with the updated path.
     #
     # @param segment [String]
     # @return [Decoding::Failure]
     def push(segment)
-      @path << segment
-      self
+      self.class.new(@msg, @path + [segment])
     end
 
     def to_s

data/lib/decoding/result.rb

@@ -52,6 +52,10 @@ module Decoding
       freeze
     end
 
+    def deconstruct
+      [value]
+    end
+
     def eql?(other)
       other.is_a?(self.class) && value == other.value
     end

data/lib/decoding/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Decoding
-  VERSION = "0.2.2"
+  VERSION = "0.2.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decoding
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Arjan van der Gaag
@@ -15,11 +15,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/hooks/allow-rspec.sh"
+- ".claude/settings.json"
 - ".rspec"
 - ".rubocop.yml"
 - ".tool-versions"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -31,12 +34,14 @@ files:
 - lib/decoding/decoders/any.rb
 - lib/decoding/decoders/array.rb
 - lib/decoding/decoders/at.rb
+- lib/decoding/decoders/fail.rb
 - lib/decoding/decoders/field.rb
 - lib/decoding/decoders/hash.rb
 - lib/decoding/decoders/index.rb
 - lib/decoding/decoders/map.rb
 - lib/decoding/decoders/match.rb
 - lib/decoding/decoders/pass.rb
+- lib/decoding/decoders/succeed.rb
 - lib/decoding/failure.rb
 - lib/decoding/result.rb
 - lib/decoding/version.rb
@@ -48,6 +53,9 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/avdgaag/decoding
   source_code_uri: https://github.com/avdgaag/decoding
+  changelog_uri: https://github.com/avdgaag/decoding/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/avdgaag/decoding/issues
+  documentation_uri: https://rubydoc.info/gems/decoding
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: