flexor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 823be7501c328a913f46121e7aa40b37fde22d73505f92928087f0d68b9355e2
+  data.tar.gz: 717311911cdb6e059859390ef9b238c1f524ed96d52071563cbc9f56568d119a
+SHA512:
+  metadata.gz: 9abb50d29119d0cb6deb40e8a14dc1bed3cf860fc65eb599adb1fc8f740374fc664440dc55cc5b3868b1cbe93e44d262ea338ab544f0fc590d587d1d738ab047
+  data.tar.gz: 531b16d783d2f49bf68edd73a27b47a7565f17f6a465b12b64f9d9542e4d781b9b4dfdacf345b941bad847e36afdee523b8666f42d09cb6ef0dc9f4de393a9c4

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,394 @@
+# ===========================================================================
+# RuboCop Configuration
+#
+# Base: Stock RuboCop defaults
+# AI guardrails: rubocop-claude plugin (all Claude/ cops + stricter metrics)
+# Performance: rubocop-performance (with chain-hostile cops disabled)
+#
+# Philosophy: idiomatic Ruby, pipeline-style chaining, strict for AI agents,
+# readable for humans.
+# ===========================================================================
+
+plugins:
+  - rubocop-claude
+  - rubocop-performance
+  - rubocop-rspec
+  - rubocop-md
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.4
+
+# ===========================================================================
+# Overrides from stock — personal style preferences
+# ===========================================================================
+
+# Double quotes everywhere. One less decision to make.
+#
+#   # bad
+#   name = 'Alice'
+#
+#   # good
+#   name = "Alice"
+#   greeting = "Hello, #{name}"
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Frozen string literal is transitional cruft. Ruby 3.4 has chilled strings,
+# full default freeze is coming in a future Ruby.
+# EnforcedStyle: never actively removes existing magic comments via autocorrect.
+#
+#   # bad — autocorrect will strip this
+#   # frozen_string_literal: true
+#
+#   class Foo
+#   end
+#
+#   # good
+#   class Foo
+#   end
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+# Pipeline style. Chaining multi-line blocks is the whole point.
+#
+#   # good — this is how we write Ruby
+#   users
+#     .select { it.active? }
+#     .map(&:name)
+#     .sort
+#
+#   # bad — stock rubocop wants you to break this into temp variables
+#   active = users.select { it.active? }
+#   names = active.map(&:name)
+#   names.sort
+Style/MultilineBlockChain:
+  Enabled: false
+
+# Block delimiters are a taste call. Pipeline code uses braces for chaining,
+# do/end for side effects. No cop captures this nuance.
+#
+#   # good — braces for functional transforms
+#   users.map { it.name.downcase }
+#
+#   # good — do/end for side effects
+#   users.each do |user|
+#     send_notification(user)
+#     log_activity(user)
+#   end
+Style/BlockDelimiters:
+  Enabled: false
+
+# Write arrays like arrays.
+#
+#   # bad
+#   colors = %w[red green blue]
+#   statuses = %i[active inactive pending]
+#
+#   # good
+#   colors = ["red", "green", "blue"]
+#   statuses = [:active, :inactive, :pending]
+Style/WordArray:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+# Argument indentation: consistent 2-space indent, not aligned to first arg.
+#
+#   # bad — renaming the method cascades whitespace changes
+#   some_method(arg1,
+#               arg2,
+#               arg3)
+#
+#   # good
+#   some_method(
+#     arg1,
+#     arg2,
+#     arg3
+#   )
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
+# Dot-aligned chaining. Dots form a visual column.
+# rubocop-claude sets indented — we override back to aligned.
+#
+#   # bad (indented)
+#   users.where(active: true)
+#     .order(:name)
+#     .limit(10)
+#
+#   # good (aligned)
+#   users.where(active: true)
+#        .order(:name)
+#        .limit(10)
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: aligned
+
+# ===========================================================================
+# Overrides from rubocop-claude — loosen where pipeline style conflicts
+# ===========================================================================
+
+# rubocop-claude sets MaxSafeNavigationChain: 1. That's too tight for
+# chaining code at boundaries (controllers, API responses).
+#
+#   # bad — 3+ deep, hiding a nil propagation problem
+#   user&.profile&.settings&.theme
+#
+#   # good — two-step is normal for optional associations
+#   user&.profile&.avatar_url
+#
+#   # good — trust internal code, no &. needed
+#   user.profile.settings.theme
+Claude/NoOverlyDefensiveCode:
+  MaxSafeNavigationChain: 2
+
+Style/SafeNavigation:
+  MaxChainLength: 2
+
+# Allow `return a, b` for tuple-style returns.
+# rubocop-claude sets this; declared here to survive load-order surprises.
+#
+#   # bad (stock rubocop flags this)
+#   def swap(a, b)
+#     return b, a
+#   end
+#
+#   # good (we allow it)
+#   def swap(a, b)
+#     return b, a
+#   end
+#
+#   # still flagged — redundant single return
+#   def name
+#     return @name
+#   end
+Style/RedundantReturn:
+  AllowMultipleReturnValues: true
+
+# ===========================================================================
+# Overrides from rubocop-performance — disable chain-hostile cops
+# ===========================================================================
+Performance:
+  Exclude:
+    - "spec/**/*"
+
+# ChainArrayAllocation flags idiomatic pipelines for microsecond gains.
+# If we need real throughput we parallelize, not uglify.
+#
+#   # "bad" according to this cop — but we write this deliberately
+#   users.select(&:active?).map(&:name).sort
+#
+#   # "good" according to this cop — mutating, unreadable, not our style
+#   users.select!(&:active?)
+#   users.map!(&:name)
+#   users.sort!
+Performance/ChainArrayAllocation:
+  Enabled: false
+
+# MapMethodChain wants to collapse chained maps into one block.
+# That's the opposite of pipeline decomposition.
+#
+#   # "bad" according to this cop — but each step is atomic and named
+#   users
+#     .map(&:name)
+#     .map(&:downcase)
+#
+#   # "good" according to this cop — combines concerns into one block
+#   users.map { it.name.downcase }
+Performance/MapMethodChain:
+  Enabled: false
+
+# ===========================================================================
+# Additional tightening — not set by stock or rubocop-claude
+# ===========================================================================
+
+# Short blocks push toward small chained steps instead of fat lambdas.
+# Stock default is 25. rubocop-claude doesn't touch it. We want 8.
+#
+#   # bad — too much in one block, decompose into a pipeline
+#   users.map { |user|
+#     name = user.full_name
+#     parts = name.split(" ")
+#     first = parts.first
+#     last = parts.last
+#     domain = user.email.split("@").last
+#     "#{first}.#{last}@#{domain}".downcase
+#   }
+#
+#   # good — each step is clear
+#   users
+#     .map(&:full_name)
+#     .map { it.split(" ") }
+#     .map { "#{it.first}.#{it.last}" }
+#     .map(&:downcase)
+Metrics/BlockLength:
+  Max: 8
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+  AllowedMethods:
+    - describe
+    - context
+    - shared_examples
+    - shared_examples_for
+    - shared_context
+
+# Anonymous forwarding (*, **, &) breaks TruffleRuby, JRuby, and
+# Ruby < 3.2. Named args are explicit and portable.
+#
+#   # bad — anonymous forwarding, not portable
+#   def process(*, **, &)
+#     other_method(*, **, &)
+#   end
+#
+#   # good — named, works everywhere, readable
+#   def process(*args, **kwargs, &block)
+#     other_method(*args, **kwargs, &block)
+#   end
+Style/ArgumentsForwarding:
+  Enabled: false
+
+# Explicit begin/rescue/end is clearer than implicit method-body rescue.
+# The begin block scopes what's being rescued. Without it, the rescue
+# looks like it belongs to the method signature.
+#
+#   # bad — what exactly is being rescued here?
+#   def process
+#     logger.info("starting")
+#     result = dangerous_call
+#     logger.info("done")
+#   rescue NetworkError => e
+#     retry_later(e)
+#   end
+#
+#   # good — begin scopes the danger
+#   def process
+#     logger.info("starting")
+#     begin
+#       result = dangerous_call
+#     rescue NetworkError => e
+#       retry_later(e)
+#     end
+#     logger.info("done")
+#   end
+Style/RedundantBegin:
+  Enabled: false
+
+# Classes get rdoc. Run `rake rdoc` and keep it honest.
+#
+#   # bad
+#   class UserService
+#     def call(user) = process(user)
+#   end
+#
+#   # good
+#   # Handles user lifecycle operations including activation,
+#   # deactivation, and profile updates.
+#   class UserService
+#     def call(user) = process(user)
+#   end
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - "spec/**/*"
+    - "test/**/*"
+
+# Trailing commas in multiline literals and arguments.
+# Cleaner diffs — adding an element doesn't touch the previous line.
+# Also saves keystrokes when appending.
+#
+#   # bad
+#   method_call(
+#     arg1,
+#     arg2
+#   )
+#
+#   # good
+#   method_call(
+#     arg1,
+#     arg2,
+#   )
+#
+#   # bad
+#   hash = {
+#     name: "Alice",
+#     age: 30
+#   }
+#
+#   # good
+#   hash = {
+#     name: "Alice",
+#     age: 30,
+#   }
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+# ===========================================================================
+# RSpec — rubocop-rspec overrides
+# ===========================================================================
+
+# Not every describe block wraps a class. Feature specs, request specs,
+# and integration tests describe behavior, not objects.
+#
+#   # "bad" according to this cop — but perfectly valid
+#   RSpec.describe "User registration flow" do
+#     it "sends a welcome email" do
+#       ...
+#     end
+#   end
+#
+#   # this cop only wants
+#   RSpec.describe User do
+#     ...
+#   end
+RSpec/DescribeClass:
+  Enabled: false
+
+# Subject placement is a readability call, not a rule. Sometimes
+# let blocks need to come first to make subject comprehensible.
+#
+#   # "bad" according to this cop
+#   let(:user) { create(:user) }
+#   subject { described_class.new(user) }
+#
+#   # cop wants subject first — but then you're reading
+#   # `described_class.new(user)` before knowing what `user` is
+RSpec/LeadingSubject:
+  Enabled: false
+
+# Block style for expect { }.to change { } reads like a sentence
+# and makes the mutation scope explicit.
+#
+#   # bad (method style)
+#   expect { user.activate! }.to change(user, :active?).from(false).to(true)
+#
+#   # good (block style)
+#   expect { user.activate! }.to change { user.active? }.from(false).to(true)
+RSpec/ExpectChange:
+  EnforcedStyle: block
+
+RSpec/NamedSubject:
+  Enabled: false
+
+# PROJECT SPECIFIC:
+#
+# Behavior is very intricate here and warrants separation
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Max: 3

data/.ruby-version

@@ -0,0 +1 @@
+3.4.8

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Gillis
+
+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,218 @@
+# Flexor
+
+A Hash-like data store that does what you tell it to do.
+
+Flexor gives you autovivifying nested access, nil-safe chaining, and seamless conversion between hashes and method-style access. Built for spikes, prototyping, and anywhere you need a flexible data container without upfront schema design.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add flexor
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install flexor
+
+## Usage
+
+### Construction
+
+From a hash:
+
+```ruby
+store = Flexor.new({ user: { name: "Alice", address: { city: "NYC" } } })
+store.user.name           # => "Alice"
+store.user.address.city   # => "NYC"
+```
+
+From JSON:
+
+```ruby
+store = Flexor.from_json('{"api": {"version": 2}}')
+store.api.version # => 2
+```
+
+### Accessing Properties
+
+Method access and bracket access are interchangeable:
+
+```ruby
+store = Flexor.new({ name: "Alice" })
+store.name      # => "Alice"
+store[:name]    # => "Alice"
+```
+
+Nested chaining works to any depth:
+
+```ruby
+store = Flexor.new
+store.config.database.host = "localhost"
+store.config.database.port = 5432
+store.config.database.host # => "localhost"
+```
+
+### Safe Chaining
+
+Accessing an unset property returns a nil-like Flexor instead of raising. You can chain as deep as you want without guard clauses:
+
+```ruby
+store = Flexor.new
+store.anything.deeply.nested.nil? # => true
+store.missing.nil? # => true
+store.missing.to_s                  # => ""
+"Hello #{store.ghost}"              # => "Hello "
+```
+
+### Assignment Vivifies
+
+When you assign a hash or array of hashes, Flexor auto-converts them so chaining continues to work:
+
+```ruby
+store = Flexor.new
+store.config = { db: { host: "localhost" } }
+store.config.db.host   # => "localhost"
+store[:config].class   # => Flexor
+
+store.items = [{ id: 1 }, { id: 2 }]
+store.items.first.id   # => 1
+```
+
+### Deep Merge
+
+`merge` returns a new Flexor; `merge!` mutates in place. Both deep merge nested structures:
+
+```ruby
+defaults = Flexor.new({ db: { host: "localhost", port: 5432 }, log: "info" })
+overrides = { db: { port: 3306, name: "mydb" }, log: "debug" }
+
+config = defaults.merge(overrides)
+config.db.host   # => "localhost"  (preserved from defaults)
+config.db.port   # => 3306         (overridden)
+config.db.name   # => "mydb"       (added)
+config.log       # => "debug"      (overridden)
+```
+
+### Serialization
+
+`to_json` converts to JSON via `to_h`:
+
+```ruby
+store = Flexor.new({ user: { name: "Alice" }, tags: ["admin"] })
+store.to_json # => '{"user":{"name":"Alice"},"tags":["admin"]}'
+
+# Round-trips with from_json
+Flexor.from_json(store.to_json).user.name # => "Alice"
+```
+
+### Deleting Keys
+
+```ruby
+store = Flexor.new({ a: 1, b: 2, c: 3 })
+store.delete(:b) # => 2
+store.to_h # => { a: 1, c: 3 }
+```
+
+### Raw Storage
+
+If you need to store a raw Hash without conversion, use `set_raw`:
+
+```ruby
+store = Flexor.new
+store.set_raw(:headers, { "Content-Type" => "application/json" })
+store[:headers].class # => Hash
+```
+
+### Converting Back
+
+`to_h` recursively converts back to plain hashes. Round-trips are lossless:
+
+```ruby
+original = { users: [{ name: "Bob" }], meta: { version: 1 } }
+Flexor.new(original).to_h == original # => true
+```
+
+Autovivified-but-never-written paths don't appear in `to_h`:
+
+```ruby
+store = Flexor.new({ real: "data" })
+store.phantom.deep.chain   # read-only access
+store.to_h                 # => { real: "data" }
+```
+
+### Pattern Matching
+
+Hash patterns via `deconstruct_keys`:
+
+```ruby
+config = Flexor.new({ db: { host: "pg", port: 5432 }, cache: "redis" })
+
+case config
+in { db: { host: String => host }, cache: "redis" }
+  puts "db host=#{host}, cache=redis"
+end
+```
+
+Array patterns via `deconstruct`:
+
+```ruby
+point = Flexor.new({ x: 3, y: 4 })
+
+case point
+in [Integer => x, Integer => y]
+  puts "Point(#{x}, #{y})"
+end
+```
+
+### Hash-like Methods
+
+```ruby
+store = Flexor.new({ a: 1, b: 2, c: 3 })
+store.keys       # => [:a, :b, :c]
+store.values     # => [1, 2, 3]
+store.size       # => 3
+store.empty?     # => false
+store.key?(:a)   # => true
+
+store.each { |k, v| puts "#{k}: #{v}" }
+store.map { |k, v| [k, v * 10] }
+store.select { |_k, v| v > 1 }
+```
+
+### Equality
+
+```ruby
+a = Flexor.new({ x: 1 })
+b = Flexor.new({ x: 1 })
+a == b        # => true
+a == { x: 1 } # => true
+Flexor.new.nil? # => true
+```
+
+### Freezing
+
+```ruby
+store = Flexor.new({ locked: true })
+store.freeze
+store.locked       # => true
+store.new_key = 1  # => FrozenError
+```
+
+### Copying
+
+`dup` and `clone` create shallow copies:
+
+```ruby
+original = Flexor.new({ a: 1 })
+copy = original.dup
+copy.b = 2
+original.key?(:b) # => false
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. Run `rake` to run both tests and rubocop.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]