darthjee-core_ext 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8fa1c8ad67a3ebb2c4e0d3e44d2ece2404cb679e
-  data.tar.gz: 2362ff51b7d433bc82fb51314496af9801145bde
+SHA256:
+  metadata.gz: df2eab1682af7c7411711127f5ed298a7084c802b5f13b9b2f0e809040488edf
+  data.tar.gz: 4bc429c6fbd6a6f920c6ea8657260a975ef475db5115919ee4f46927c1a49b1e
 SHA512:
-  metadata.gz: ac6b7fe0376149cb813893fdb64822f69e0f78972b21bb19d8d1be2192b395b386a2d565956197c613576aff80075d1eb609683af342a3b0728553c6fb32e9a8
-  data.tar.gz: 278121be9eb0a87815c2b878059a37c583b27296d9667c848e75a9f05bdd4b09b85051a0f2c254aafbb83da0691d6fa6fe5d611810536bac3e62b3056b52701f
+  metadata.gz: e85edf7601b5ba6196329fc472d15f6f67ef6df19bcf42addbea475fc0f8759000109d5d84a5888d2a5073d788648848404815c104ec15ebea0d6fc211a8f035
+  data.tar.gz: d726c8c5cf025ddf824fd9449392d496015f4ff83adec37531746446d0cdee7dfd07fff3381aa2baca50dad986097baca57a3151cc6ba76b26675d90220cdaf0

data/.circleci/config.yml

@@ -1,31 +1,82 @@
 version: 2
+workflows:
+  version: 2
+  test-and-build:
+    jobs:
+      - test:
+          filters:
+            tags:
+              only: /.*/
+      - checks:
+          filters:
+            tags:
+              only: /.*/
+      - build-and-release:
+          requires: [test, checks]
+          filters:
+            tags:
+              only: /\d+\.\d+\.\d+/
+            branches:
+              only:
+                - main
 jobs:
-  build:
+  test:
     docker:
-      - image: darthjee/circleci_ruby_gems_240:0.0.2
+      - image: darthjee/circleci_ruby_331:1.1.1
+        environment:
+          PROJECT: core_ext
     steps:
       - checkout
-      - run:
-          name: Prepare Coverage Test Report
-          command: cc-test-reporter before-build
       - run:
           name: Bundle Install
           command: bundle install
       - run:
           name: RSpec
           command: bundle exec rspec
+      - run:
+          name: Upload coverage to Codacy
+          command: bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r coverage/lcov/project.lcov
+  checks:
+    docker:
+      - image: darthjee/circleci_ruby_331:1.1.1
+        environment:
+          PROJECT: core_ext
+    steps:
+      - checkout
+      - run:
+          name: Bundle Install
+          command: bundle install
       - run:
           name: Rubocop
           command: rubocop
-      - run:
-          name: Coverage Test Report
-          command: cc-test-reporter after-build --exit-code $?
       - run:
           name: Yardstick coverage check
           command: bundle exec rake verify_measurements
       - run:
           name: Check version documentation
-          command: scripts/check_readme.sh
+          command: PROJECT=darthjee-core_ext check_readme.sh
       - run:
           name: Rubycritcs check
-          command: scripts/rubycritic.sh
+          command: rubycritic.sh
+      - run:
+          name: Check unit tests
+          command: check_specs
+  build-and-release:
+    docker:
+      - image: darthjee/circleci_ruby_331:1.1.1
+        environment:
+          PROJECT: core_ext
+    steps:
+      - checkout
+      - run:
+          name: Bundle Install
+          command: bundle install
+      - run:
+          name: Signin
+          command: build_gem.sh signin
+      - run:
+          name: Build Gem
+          command: PROJECT=darthjee-core_ext build_gem.sh build
+      - run:
+          name: Push Gem
+          command: PROJECT=darthjee-core_ext build_gem.sh push

data/.github/copilot-instructions.md

@@ -0,0 +1,99 @@
+# GitHub Copilot Instructions for `darthjee/core_ext`
+
+## Project Overview
+
+`core_ext` is a Ruby gem that **adds methods to Ruby's standard objects** (core extensions). It extends built-in classes such as `Array`, `Hash`, `Symbol`, `Enumerable`, `Date`, `Object`, `Numeric`, and others with additional utility methods, while maintaining compatibility and predictable behavior.
+
+- Gem name: `darthjee-core_ext`
+- YARD docs: [rubydoc.info/gems/darthjee-core_ext](https://www.rubydoc.info/gems/darthjee-core_ext)
+- Extensions live under `lib/darthjee/core_ext/`
+
+---
+
+## Language
+
+- All code, comments, commit messages, pull request titles, PR descriptions, review comments, and documentation **must be written in English**.
+- No exceptions: even if the author's primary language is not English, all contributions to this repository must use English.
+
+---
+
+## Testing
+
+- **Every new feature or bug fix must include tests.**
+- Tests are written using RSpec and live under `spec/`.
+- Follow the existing test structure: unit tests mirror the `lib/` directory layout under `spec/lib/`.
+- If a file does not have a corresponding spec file and **intentionally** has no tests (e.g., it is a pure re-export or namespace file), it must be listed in `config/check_specs.yml` under the `ignore:` key.
+- Do **not** add files to `config/check_specs.yml` as a shortcut to avoid writing tests. Only files that genuinely cannot or should not have direct tests belong there.
+- Run the full test suite before opening a PR: `bundle exec rspec`.
+
+---
+
+## Documentation
+
+- All public methods must be documented using **YARD** syntax.
+- Use `@param`, `@return`, `@example`, and `@raise` tags where applicable.
+- Include at least one `@example` block for methods that demonstrate non-trivial behavior.
+- Keep documentation close to the code (inline in the source file).
+- Example:
+
+  ```ruby
+  # Converts the hash keys to camel case.
+  #
+  # @param [Symbol] type the case type (:lower or :upper)
+  # @return [Hash] a new hash with camel-cased keys
+  # @example
+  #   { my_key: 1 }.camelize_keys #=> { myKey: 1 }
+  def camelize_keys(type = :lower)
+    # ...
+  end
+  ```
+
+---
+
+## Design Principles
+
+### Single Responsibility
+
+- Classes and methods should have **one reason to change** (Single Responsibility Principle).
+- Prefer small, focused methods. If a method is doing more than one thing, extract the extra responsibility into a helper method or a collaborator class.
+- Follow the approach described by **Sandi Metz** in *99 Bottles of OOP*:
+  - Prefer simple, obvious code over clever code.
+  - Let the tests drive refactoring: make it work, make it right, make it fast.
+  - Use small objects that collaborate through messages.
+  - Avoid premature abstraction; introduce it only when duplication demands it.
+
+### Law of Demeter
+
+- Avoid **Law of Demeter violations**: do not chain method calls across multiple object boundaries (e.g., `a.b.c.d`).
+- Instead, delegate behavior closer to the data: expose a method on the intermediate object, or use a helper that encapsulates the traversal.
+- Code that violates the Law of Demeter increases coupling and makes refactoring harder.
+
+  ```ruby
+  # Avoid
+  user.address.city.upcase
+
+  # Prefer
+  user.city_upcased
+  ```
+
+### General Style
+
+- Prefer composition over inheritance.
+- Keep class hierarchies shallow.
+- Avoid monkey-patching outside of the intended extension pattern of this gem.
+- New core extensions must be clearly scoped to a specific Ruby class and added in the appropriate file under `lib/darthjee/core_ext/`.
+
+---
+
+## Pull Request Guidelines
+
+- PR titles and descriptions must be in **English**.
+- Every PR should include:
+  - A clear description of what changed and why.
+  - References to any related issues.
+  - Confirmation that tests pass locally.
+- Reviewers should check that:
+  - New code is covered by tests.
+  - Documentation follows YARD conventions.
+  - Design principles (single responsibility, Demeter) are respected.
+  - No file was added to `config/check_specs.yml` without a valid justification.

data/.github/core_ext-usage.md

@@ -0,0 +1,324 @@
+# Using `darthjee-core_ext` in Your Project
+
+This file is intended to be copied into the `.github/` folder of other projects.
+It provides GitHub Copilot (and developers) with a clear, actionable guide on how
+to use the [`darthjee-core_ext`](https://github.com/darthjee/core_ext) Ruby gem.
+
+---
+
+## What Is `core_ext`?
+
+`darthjee-core_ext` is a Ruby gem that extends Ruby's built-in (core) classes with
+additional utility methods. It follows the convention of "core extensions" — monkey-patching
+standard objects such as `Array`, `Hash`, `Symbol`, `Enumerable`, `Date`, `Object`,
+`Numeric`, and `Math` with useful helpers, while maintaining predictable behavior.
+
+- **Gem name**: `darthjee-core_ext`
+- **Source**: <https://github.com/darthjee/core_ext>
+- **YARD docs**: <https://www.rubydoc.info/gems/darthjee-core_ext>
+- **Current stable release**: 3.0.0
+
+---
+
+## Adding the Gem to Your Project
+
+### Via RubyGems (recommended)
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'darthjee-core_ext'
+```
+
+Or pin a specific version for reproducible builds:
+
+```ruby
+gem 'darthjee-core_ext', '~> 3.0'
+```
+
+### Via GitHub (source)
+
+```ruby
+gem 'darthjee-core_ext',
+    github: 'darthjee/core_ext',
+    branch: 'main'
+```
+
+---
+
+## Installing
+
+After adding the gem to your `Gemfile`, run:
+
+```shell
+bundle install
+```
+
+Or install it system-wide:
+
+```shell
+gem install darthjee-core_ext
+```
+
+---
+
+## Loading the Gem
+
+When using Bundler (Rails, typical Ruby apps), the gem is loaded automatically via
+`Bundler.require`. No explicit `require` is needed.
+
+In plain Ruby scripts or when Bundler auto-require is disabled, add:
+
+```ruby
+require 'darthjee/core_ext'
+```
+
+---
+
+## Extensions Provided
+
+### `Hash`
+
+| Method | Description |
+|---|---|
+| `#append_to_keys` | Appends a string to every key |
+| `#prepend_to_keys` | Prepends a string to every key |
+| `#camelize_keys` / `#camelize_keys!` | Converts keys to CamelCase |
+| `#lower_camelize_keys` / `#lower_camelize_keys!` | Converts keys to lowerCamelCase |
+| `#underscore_keys` / `#underscore_keys!` | Converts keys to snake_case |
+| `#change_keys` / `#change_keys!` | Transforms keys with a block |
+| `#chain_change_keys` / `#chain_change_keys!` | Transforms keys by chaining method calls |
+| `#change_values` / `#change_values!` | Transforms values with a block (optionally recursive) |
+| `#chain_fetch` | Fetches nested keys in a chain |
+| `#exclusive_merge` / `#exclusive_merge!` | Merges only existing keys |
+| `#remap_keys` / `#remap_keys!` | Renames keys based on a mapping hash |
+| `#sort_keys` / `#sort_keys!` | Sorts the hash by its keys |
+| `#squash` / `#squash!` | Flattens a deep hash into a single-level hash |
+| `#to_deep_hash` / `#to_deep_hash!` | Expands a squashed hash back into a deep hash |
+| `#map_to_hash` | Maps values keeping original keys |
+| `#transpose` / `#transpose!` | Swaps keys with values |
+
+### `Array`
+
+| Method | Description |
+|---|---|
+| `#as_hash` | Zips the array with a keys array into a Hash |
+| `#average` | Returns the arithmetic average of the elements |
+| `#chain_map` | Applies `.map` in a chain of method calls |
+| `#mapk` | Maps by fetching nested keys from hashes inside the array |
+| `#procedural_join` | Joins elements with a dynamically computed separator |
+| `#random` | Returns a random element |
+| `#random!` | Removes and returns a random element |
+
+### `Symbol`
+
+| Method | Description |
+|---|---|
+| `#camelize` | Camelizes the symbol (`:my_sym` → `:MySym`) |
+| `#underscore` | Underscores a camelized symbol (`:MySym` → `:my_sym`) |
+
+### `Enumerable` (available on `Array`, `Hash`, and any `Enumerable`)
+
+| Method | Description |
+|---|---|
+| `#clean` | Returns a copy with empty values removed |
+| `#clean!` | Removes empty values in place (recursive) |
+| `#map_and_find` | Maps and stops at the first truthy result |
+| `#map_and_select` | Maps and returns only truthy results |
+| `#map_to_hash` | Maps values, using original elements as keys |
+
+### `Object` (available on every Ruby object)
+
+| Method | Description |
+|---|---|
+| `#is_any?` | Returns `true` if the object is an instance of any of the given classes |
+| `#trueful?` | Returns `true` only when the object is not `nil` (unlike `#present?`, `[]` and `{}` are trueful) |
+
+### `Date`
+
+| Method | Description |
+|---|---|
+| `#days_between` | Returns the absolute number of days between two dates |
+
+### `Math`
+
+| Method | Description |
+|---|---|
+| `.average` | Calculates the (optionally weighted) average of values |
+
+### `Class`
+
+| Method | Description |
+|---|---|
+| `.default_value` | Adds a reader that returns the same default instance every time |
+| `.default_values` | Adds multiple readers sharing the same default instance |
+| `.default_reader` | Adds a reader that returns a default value only when the instance variable was never set |
+| `.default_readers` | Adds multiple default readers sharing the same default value |
+
+---
+
+## Code Examples
+
+### Hash key transformations
+
+```ruby
+# Converting API responses from camelCase to snake_case
+response = { 'userId' => 1, 'firstName' => 'Alice' }
+response.underscore_keys  # => { 'user_id' => 1, 'first_name' => 'Alice' }
+
+# Preparing a payload for a camelCase API
+params = { user_id: 1, first_name: 'Alice' }
+params.lower_camelize_keys
+# => { userId: 1, firstName: 'Alice' }
+
+# Equivalent long form with explicit option
+params.camelize_keys(uppercase_first_letter: false)
+# => { userId: 1, firstName: 'Alice' }
+```
+
+### Fetching nested values safely
+
+```ruby
+config = { database: { primary: { host: 'localhost' } } }
+
+config.chain_fetch(:database, :primary, :host)  # => 'localhost'
+config.chain_fetch(:database, :replica, :host) { |key, _rest| "default-#{key}" }
+# => 'default-replica'
+```
+
+### Flattening and restoring deep hashes
+
+```ruby
+deep = { a: { b: [1, 2] } }
+flat = deep.squash   # => { 'a.b[0]' => 1, 'a.b[1]' => 2 }
+flat.to_deep_hash    # => { 'a' => { 'b' => [1, 2] } }
+```
+
+### Exclusive merge (update only existing keys)
+
+```ruby
+defaults = { timeout: 30, retries: 3 }
+overrides = { retries: 5, unknown_key: 'ignored' }
+
+defaults.exclusive_merge(overrides)  # => { timeout: 30, retries: 5 }
+```
+
+### Array utilities
+
+```ruby
+# Zip an array with keys into a Hash
+values = [10, 20, 30]
+values.as_hash(%i[x y z])  # => { x: 10, y: 20, z: 30 }
+
+# Chain map calls
+[:hello, :world].chain_map(:to_s, :upcase)  # => ['HELLO', 'WORLD']
+
+# Fetch nested keys from an array of hashes
+records = [{ user: { id: 1 } }, { user: { id: 2 } }]
+records.mapk(:user, :id)  # => [1, 2]
+```
+
+### Symbol utilities
+
+```ruby
+:my_method_name.camelize         # => :MyMethodName
+:my_method_name.camelize(:lower) # => :myMethodName
+:MyMethodName.underscore         # => :my_method_name
+```
+
+### Enumerable cleaning
+
+```ruby
+data = { name: 'Alice', nickname: nil, tags: [], meta: {} }
+data.clean   # => { name: 'Alice' }
+
+mixed = [1, nil, '', [], {}, 'hello']
+mixed.clean  # => [1, 'hello']
+```
+
+### Object helpers
+
+```ruby
+value = 42
+value.is_any?(String, Symbol)         # => false
+value.is_any?(String, Symbol, Integer)  # => true
+
+nil.trueful?          # => false
+[].trueful?           # => true   (unlike blank?/present?)
+''.trueful?           # => true
+```
+
+### Class default readers
+
+```ruby
+class Report
+  attr_writer :title
+  default_reader :title, 'Untitled Report'
+end
+
+r = Report.new
+r.title         # => 'Untitled Report'
+r.title = 'Q1'
+r.title         # => 'Q1'
+r.title = nil
+r.title         # => nil  (nil is respected; differs from default_value)
+```
+
+### Math weighted average
+
+```ruby
+# Simple average
+Math.average([10, 20, 30])  # => 20.0
+
+# Weighted average (value => weight)
+Math.average(10 => 1, 20 => 2, 30 => 1)  # => 20.0
+```
+
+---
+
+## Best Practices and Caveats
+
+### Monkey-patching awareness
+
+`core_ext` extends Ruby's built-in classes globally. This means:
+
+- All objects of the extended classes gain the new methods **throughout your entire application**, including third-party gems.
+- **Name collision risk**: if another gem or your application already defines a method with the same name on the same class, the last `require`/`load` wins. Review the method list above before adoption and check for conflicts.
+- In libraries (gems) intended for wide reuse, prefer not requiring `core_ext` at the top level unless you own all consumers.
+
+### Recursive options
+
+Several `Hash` methods (`change_keys`, `camelize_keys`, `underscore_keys`, `change_values`, `clean!`) operate recursively by default, descending into nested arrays and hashes. Pass `recursive: false` when you only need shallow transformation to avoid unintended side-effects on nested structures.
+
+### Bang (`!`) methods vs. non-bang methods
+
+Methods ending with `!` mutate the receiver **in place**. Use them when you are sure you do not need the original structure. Use the non-bang variants to return a transformed copy.
+
+### Versioning
+
+Pin to a minor version to avoid unexpected breaking changes:
+
+```ruby
+gem 'darthjee-core_ext', '~> 3.0'
+```
+
+Check the [CHANGELOG / releases page](https://github.com/darthjee/core_ext/releases) before upgrading.
+
+---
+
+## Running the Test Suite / Contributing
+
+If you are contributing to `core_ext` itself or want to verify its behavior locally:
+
+```shell
+# Install dependencies
+bundle install
+
+# Run the full test suite
+bundle exec rspec
+
+# Run a single spec file
+bundle exec rspec spec/lib/darthjee/core_ext/hash_spec.rb
+```
+
+Tests live under `spec/` and mirror the structure of `lib/`. Every public method must have a corresponding spec. See the [README](https://github.com/darthjee/core_ext/blob/main/README.md) and the repository's Copilot instructions (`.github/copilot-instructions.md`) for more details.

data/.rubocop.yml

@@ -1,12 +1,15 @@
-require: rubocop-rspec
+plugins:
+  - rubocop-rspec
+  - rubocop-rake
 inherit_from: .rubocop_todo.yml
 
 AllCops:
-  TargetRubyVersion: 2.4
+  TargetRubyVersion: 3.3
+  NewCops: enable
 
-Naming/PredicateName:
+RSpec/MultipleExpectations:
   Exclude:
-    - 'lib/darthjee/core_ext/object.rb'
+    - 'spec/integration/**/*_spec.rb'
 
 Metrics/BlockLength:
   Exclude:
@@ -18,3 +21,18 @@ RSpec/AlignLeftLetBrace:
 
 RSpec/NestedGroups:
   Max: 5
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/integration/**/*_spec.rb'
+
+Style/HashEachMethods:
+  Exclude:
+    - 'lib/darthjee/core_ext/hash/deep_hash_constructor.rb'
+    - 'lib/darthjee/core_ext/hash/squasher.rb'
+
+Gemspec/RequireMFA:
+  Enabled: false

data/.rubocop_todo.yml

@@ -1,16 +1,36 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-02-18 18:10:37 +0000 using RuboCop version 0.58.1.
+# on 2026-03-11 13:23:23 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 3
-# Configuration parameters: AggregateFailuresByDefault.
-RSpec/MultipleExpectations:
-  Max: 2
+# Offense count: 1
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
+# NamePrefix: is_, has_, have_, does_
+# ForbiddenPrefixes: is_, has_, have_, does_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicatePrefix:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/darthjee/core_ext/object.rb'
 
-# Offense count: 24
-Style/Documentation:
-  Enabled: false
+# Offense count: 4
+# Configuration parameters: AllowSubject.
+RSpec/MultipleMemoizedHelpers:
+  Max: 6
+
+# Offense count: 8
+# Configuration parameters: AllowedClasses.
+Style/OneClassPerFile:
+  Exclude:
+    - 'lib/darthjee/core_ext/array.rb'
+    - 'lib/darthjee/core_ext/class.rb'
+    - 'lib/darthjee/core_ext/date.rb'
+    - 'lib/darthjee/core_ext/hash.rb'
+    - 'lib/darthjee/core_ext/math.rb'
+    - 'lib/darthjee/core_ext/numeric.rb'
+    - 'lib/darthjee/core_ext/object.rb'
+    - 'lib/darthjee/core_ext/symbol.rb'

data/Dockerfile

@@ -1,6 +1,22 @@
-FROM darthjee/ruby_gems_240:0.0.2
+FROM darthjee/scripts:0.7.0 as scripts
 
-USER app
-COPY --chown=app ./ /home/app/app/
+FROM darthjee/ruby_331:1.1.1 as base
 
+COPY --chown=app:app ./ /home/app/app/
+
+######################################
+
+FROM base as builder
+
+COPY --chown=app:app --from=scripts /home/scripts/builder/bundle_builder.sh /usr/local/sbin/bundle_builder.sh
+
+ENV HOME_DIR /home/app
+RUN bundle_builder.sh
+
+#######################
+#FINAL IMAGE
+FROM base
+
+COPY --chown=app:app --from=builder /home/app/bundle/ /usr/local/bundle/
 RUN bundle install
+

data/Gemfile

@@ -4,3 +4,23 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in credential_builder.gemspec
 gemspec
+
+gem 'bundler',            '>= 2.5.13'
+gem 'pry',                '0.14.2'
+gem 'pry-nav',            '1.0.0'
+gem 'rake',               '13.2.1'
+gem 'reek',               '6.5.0'
+gem 'rspec',              '3.13.2'
+gem 'rspec-core',         '3.13.6'
+gem 'rspec-expectations', '3.13.5'
+gem 'rspec-mocks',        '3.13.8'
+gem 'rspec-support',      '3.13.7'
+gem 'rubocop',            '1.85.1'
+gem 'rubocop-rake',       '0.7.1'
+gem 'rubocop-rspec',      '3.9.0'
+gem 'rubycritic',         '5.0.0'
+gem 'simplecov',          '0.22.0'
+gem 'simplecov-html',     '0.13.2'
+gem 'simplecov-lcov',     '0.9.0'
+gem 'yard',               '0.9.38'
+gem 'yardstick',          '0.9.9'

data/Makefile

@@ -0,0 +1,7 @@
+PROJECT?=core_ext
+
+dev:
+	docker-compose run $(PROJECT) /bin/bash
+
+ci:
+	docker-compose run $(PROJECT)_circleci /bin/bash