facets 4.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af1581fdee797dd22551c3257c73b76e2d0e5ee659ecb60690eee877672a5a00
-  data.tar.gz: 8693eedfa8dc78cfa8c47964cac6f2834996337dc00bbf0e9672c2b664bc2cea
+  metadata.gz: db8b790b2c8e0551d30a4020f9e9a206306ef7b57dc3bb73cf75ab8bfe192b52
+  data.tar.gz: 38d282a641961639027ed77a9042de9f837d55f6d4c37935e502ed71c1b22431
 SHA512:
-  metadata.gz: e4a41b846c6bf81d6103ec0fcac3f8b729f5ab324676ab7f2b25a4126bfe878ec36a7113d58b4a7c32c5d1748cd4a1a9ae4ebba80fa82e7226c83bc7d7220af1
-  data.tar.gz: 5c32bd85bdeb4336d5774689023e73d5c7e74ee86eff5003e5ef4da1644f10c6de5c897b6a0f268f09c7976055b28acaba10cf420b546380ae21c4d73508da86
+  metadata.gz: 7e85bd3715fbf1a7c333aefbf9b9db67afe2bd7dfbfe1119a6c2af640e6f5b189518b5c59b47d36effca090d523eaf31bed497028d000691f3c5b26f15012265
+  data.tar.gz: d32670ff9724cdd492b10092970ef9cfb4716530c2aa3f6b4906846ca0e8dae45dc04336c30d78f66da41c99e00ce9cc9a23df833dd07cf66c515891e8527945

data/CONTRIBUTING.md

@@ -104,8 +104,8 @@ explanation if needed, including *when* and *why* the method could be useful.
 
 The test suite uses four tools:
 
-* **RubyTest** provides the test runner interface; `rubytest-cli` supplies the
-  `ruby-test` command used by the Rake tasks.
+* **RubyTest** provides the test runner interface and the `rubytest` command
+  used by the Rake tasks.
 * **Lemon** defines the `test_case`, `method`, and `test` structure of the unit
   tests.
 * **AE** provides assertions such as `.assert` and `expect`, used in both the
@@ -130,6 +130,12 @@ TESTS=test/core/array/test_average.rb bundle exec rake test
 The Rakefile also provides `test:core`, `test:standard`, `test:rails` and the
 corresponding `qed:*` tasks for each library area.
 
+Tests and demos of deprecated methods call them on purpose, so both suites hide
+those deprecation warnings and print a count at the end instead
+(`etc/quiet_deprecations.rb`). A deprecation warning raised from inside `lib/`
+still shows, because it means Facets calls a deprecated method itself. To see
+every warning, set `FACETS_DEPRECATIONS=show`.
+
 * A core method in `lib/core/facets/{class}/{method}.rb` normally has a Lemon
   test in `test/core/{class}/test_{method}.rb` and a QED demo in
   `demo/core/{class}/{method}.md`. Standard and rails libraries use

data/HISTORY.md

@@ -1,5 +1,70 @@
 # Facets Release History
 
+## 4.0.1 / 2026-11-02
+
+A patch release with a security fix: `require 'facets/shellwords'` replaced
+Ruby's `Shellwords.escape` with a version that left shell metacharacters
+unescaped. It also lets Rails apps that load Facets boot again, and fixes
+several methods that broke on Ruby 3.
+
+Changes:
+
+* Bug Fixes
+
+  * Security: `require 'facets/shellwords'` replaced Ruby's
+    `Shellwords.escape`, and with it `String#shellescape`, with a fallback
+    that escaped almost nothing. `Shellwords.escape("x; rm -rf ~")` came back
+    unchanged, so code that relied on it to quote shell arguments was open to
+    command injection. The fallback was meant to apply only where Ruby had no
+    `escape`, but its check never matched Ruby's definition, so it always
+    applied. It is gone, and Ruby's own `escape` is always used. The bug dates
+    back to 2010. `require 'facets'` does not load this file (#67).
+  * `require 'facets'` no longer makes `attr`, `attr_reader`, `attr_writer`,
+    `attr_accessor`, `remove_method` and `undef_method` protected; Ruby has
+    made them public since 2.5. `Module#redefine_method` is now public, like
+    ActiveSupport's, so Rails apps that load Facets no longer fail with
+    "private method 'redefine_method' called" (#292). A redefined method now
+    keeps its visibility; before, a redefined private method became public.
+  * `Enumerable#graph` (also `Hash#graph` and `#mash`) and `Interval#step`
+    without a block, and every call to `Find.select`, no longer raise
+    `ArgumentError` on Ruby 3 (#246). `facets/find/select` now also requires
+    `find` itself.
+  * `Math.percentile` returns the minimum or maximum at the extremes, as the
+    NIST method it cites specifies. `percentile([1,2,3], 90)` raised
+    `NoMethodError`, `percentile([1,2,3], 100)` returned `nil` and
+    `percentile([1,2,3], 0)` returned 3 (#289).
+  * `Kernel#deep_clone` now copies array elements and hash values at any
+    depth; before, it only copied instance variables (#11). Equal but distinct
+    objects, such as two equal strings, no longer share one copy. Hash keys,
+    and Struct and Set members, are still shared with the original.
+  * `Enumerable#map_by` maps `false` and `nil` values instead of storing the
+    whole element (#75).
+  * `Module#alias_class_method` works. It raised `NameError` on every call.
+  * `Time#round_to` no longer prints a deprecation warning. It called the
+    deprecated `Time#trunc`.
+  * The `facets/cloneable` deprecation warning recommends `Kernel#deep_clone`
+    or `initialize_copy` instead of `deep_dup`, which Facets doesn't define.
+    The 3.2.0 notes gave the same wrong advice.
+
+* Documentation
+
+  * The README names the current release (it still said 3.2.2) and shows how
+    to load chosen extensions from a Gemfile with `require: [...]` (#280).
+  * The `Shellwords.alt_escape` docs no longer suggest it for `system()`. It
+    leaves `$ ; * ? ~` and newlines unescaped, so it is not safe for untrusted
+    input.
+
+* Internal
+
+  * The tests use rubytest 0.9's own `rubytest` command instead of the
+    `rubytest-cli` gem.
+  * The test and demo runs hide the deprecation warnings they trigger on
+    purpose and print a count instead. A deprecation warning raised from
+    inside `lib/` still shows. Set `FACETS_DEPRECATIONS=show` to see every
+    warning.
+  * First tests for `Interval#step`, `Find.select` and
+    `Module#alias_class_method`.
+
 ## 4.0.0 / 2026-09-27
 
 A major release, because it changes behavior: `Kernel#try!` is now the

data/README.md

@@ -5,7 +5,7 @@
 
 **More of Ruby, one method at a time.** Facets is a collection of extensions to Ruby's core classes and standard library, plus a few small, reusable classes and modules. Most methods live in their own files, so you can load one extension, a class's extensions, or the core collection.
 
-Facets took its name in 2004, growing out of a small methods library started in 2002, and is still maintained. The current release is **3.2.2**, which requires **Ruby 3.1 or newer**. See the [release history](HISTORY.md) for changes and migration notes from earlier versions. The `main` branch also contains changes awaiting the next release.
+Facets took its name in 2004, growing out of a small methods library started in 2002, and is still maintained. The current release is **4.0.1**, which requires **Ruby 3.1 or newer**. See the [release history](HISTORY.md) for changes and migration notes from earlier versions. The `main` branch also contains changes awaiting the next release.
 
 ## Install
 
@@ -21,6 +21,12 @@ gem 'facets', require: false
 
 `require: false` lets you choose which extensions to load. Omit it if you want Bundler to load the core collection automatically.
 
+To have Bundler load only certain extensions, for example in a Rails app, list their files instead:
+
+```ruby
+gem 'facets', require: ['facets/array/to_ranges', 'facets/string/snakecase']
+```
+
 ## Choose how much to load
 
 ### One method

data/lib/core/facets/enumerable/graph.rb

@@ -26,7 +26,7 @@ module Enumerable
       end
       h
     else
-      Enumerator.new(self,:graph)
+      to_enum(:graph)
     end
   end
 

data/lib/core/facets/enumerable/map_by.rb

@@ -21,10 +21,14 @@ module Enumerable
   def map_by #:yield:
     res = {}
     each do |a|
-      k,v = yield(*a)
-      if v
+      r = yield(*a)
+      # Test whether a second value was returned, not whether it is truthy,
+      # so false and nil are mapped too.
+      if Array === r && r.size > 1
+        k, v = r
         (res[k] ||= []) << v
       else
+        k, = r
         (res[k] ||= []) << a
       end
     end

data/lib/core/facets/kernel/deep_clone.rb

@@ -1,24 +1,52 @@
 module Kernel
 
   # Deep clone an object by deep cloning every instance
-  # variable as well.
+  # variable as well, along with the elements of an Array and
+  # the values of a Hash.
+  #
+  #   a = [1, [2, [3]]]
+  #   b = a.deep_clone
+  #   b[1][1] << 4
+  #   a  #=> [1, [2, [3]]]
+  #
+  # Hash keys are not copied: Ruby already copies and freezes String
+  # keys, and a hash compared by identity needs the same key objects.
+  # Other containers, such as Struct and Set, share their members with
+  # the original.
+  #
+  # An object that is referenced more than once, including an object
+  # that contains itself, is copied once.
   #
   # Returns [Object]
 
-  def deep_clone(cache={})
+  def deep_clone(cache={}.compare_by_identity)
     return cache[self] if cache.key?(self)
 
-    copy = clone()
+    collection = (Array === self || Hash === self)
+
+    # A frozen collection's copy is filled in first, then frozen.
+    copy = collection ? clone(freeze: false) : clone
     cache[self] = copy
 
-    copy.instance_variables.each do |var|
-      val = instance_variable_get(var)
+    deep = lambda do |val|
       begin
-        val = val.deep_clone(cache)
+        val.deep_clone(cache)
       rescue TypeError
-        next
+        val
+      end
+    end
+
+    copy.instance_variables.each do |var|
+      copy.instance_variable_set(var, deep[instance_variable_get(var)])
+    end
+
+    if collection
+      if Array === copy
+        copy.map!(&deep)
+      else
+        copy.transform_values!(&deep)
       end
-      copy.instance_variable_set(var, val)
+      copy.freeze if frozen?
     end
 
     return copy

data/lib/core/facets/module/alias_class_method.rb

@@ -2,10 +2,15 @@ class Module
 
   # Alias a class method.
   #
+  #   class Greeter
+  #     def self.hello; "Hello"; end
+  #     alias_class_method :hi, :hello
+  #   end
+  #
+  #   Greeter.hi  #=> "Hello"
+  #
   def alias_class_method(name, target)
-    class << self
-      alias_method(name, target)
-    end
+    singleton_class.alias_method(name, target)
   end
 
 end

data/lib/core/facets/module/module_def.rb

@@ -16,16 +16,5 @@ class Module
     module_eval { define_method name, &blk }
   end
 
-  #--
-  # TODO: Why are we making these protected,
-  # and where should these really go in Facets?
-  #++
-  protected :attr
-  protected :attr_reader
-  protected :attr_writer
-  protected :attr_accessor
-  protected :remove_method
-  protected :undef_method
-
 end
 

data/lib/core/facets/module/redefine_method.rb

@@ -1,7 +1,5 @@
 class Module
 
-  private
-
   # Creates a new method for a pre-existing method.
   #
   # If _aka_ is given, then the method being redefined will
@@ -21,14 +19,25 @@ class Module
   #
   #   Greeter.new.hello   #=> "Hello, friend!"
   #
+  # The new method keeps the visibility of the one it replaces. Like
+  # ActiveSupport's Module#redefine_method, this is public.
+  #
   # CREDIT: Trans
 
   def redefine_method(sym, aka=nil, &blk)
+    visibility = if private_method_defined?(sym)
+                   :private
+                 elsif protected_method_defined?(sym)
+                   :protected
+                 else
+                   :public
+                 end
     alias_method(aka, sym) if aka
     ## prevent warning about method overwrite
     begin remove_method(sym) rescue NameError end
-    ## define replacelemt method
+    ## define replacement method
     define_method(sym, &blk)
+    __send__(visibility, sym)
   end
 
   #

data/lib/core/facets/time/round_to.rb

@@ -14,7 +14,7 @@ class Time
   # TODO: Fractional seconds should round the usec.
   #
   def round_to(seconds)
-    (self + seconds / 2.0).trunc(seconds)
+    (self + seconds / 2.0).floor_to(seconds)
   end
 
 end

data/lib/core/facets/version.rb

@@ -1,3 +1,3 @@
 module Facets
-  VERSION = '4.0.0'
+  VERSION = '4.0.1'
 end

data/lib/standard/facets/cloneable.rb

@@ -1,7 +1,8 @@
-# @deprecated Use deep_dup/deep_clone instead, or define your own
-#   initialize_copy method.
+# @deprecated Use Kernel#deep_clone (`require 'facets/kernel/deep_clone'`)
+#   instead, or define your own initialize_copy method.
 #   Scheduled for removal after 2027-09-30.
-warn "facets/cloneable is deprecated. Use deep_dup/deep_clone instead. It will be removed after 2027-09-30.", uplevel: 1
+warn "facets/cloneable is deprecated. Use Kernel#deep_clone (require 'facets/kernel/deep_clone') " \
+     "or define your own initialize_copy instead. It will be removed after 2027-09-30.", uplevel: 1
 
 module Cloneable
 

data/lib/standard/facets/find/select.rb

@@ -1,3 +1,5 @@
+require 'find'
+
 module Find
   # Identical to find except select returns the matching files as an array.
   # (find returns nil, which is not very useful if you actually wanted an array.)
@@ -8,7 +10,7 @@ module Find
   #
   # CREDIT: Tyler Rick
   def self.select(*paths, &block)
-    Enumerator.new(self, :find, *paths).select{|value| yield value}
+    find(*paths).select(&block)
   end
 end
 

data/lib/standard/facets/interval.rb

@@ -257,7 +257,7 @@ class Interval
         end
       end
     else
-      Enumerator.new(self, :step, n, d)
+      to_enum(:step, n, d)
     end
   end
 

data/lib/standard/facets/math/percentile.rb

@@ -16,19 +16,24 @@ module Math
   #   require 'facets/math/percentile'
   #
   def self.percentile(array, pcnt)
-    sorted_array = array.sort
-
     return nil if array.length == 0
 
+    sorted_array = array.sort
+
     rank  = (pcnt.to_f / 100) * (array.length + 1)
     whole = rank.truncate
- 
+
+    # A rank below 1 or past the last value is clamped to the minimum or
+    # maximum, as NIST specifies.
+    return sorted_array.first if whole < 1
+    return sorted_array.last  if whole >= array.length
+
     # if has fractional part
     if whole != rank
       s0 = sorted_array[whole - 1]
       s1 = sorted_array[whole]
 
-      f = (rank - rank.truncate).abs
+      f = rank - whole
 
       return (f * (s1 - s0)) + s0
     else

data/lib/standard/facets/shellwords.rb

@@ -4,21 +4,17 @@ module Shellwords
 
   module_function
 
-  # Escape special characters used in most unix shells
-  # to use it, eg. with system().
+  # Escape backslash, tab, space, and the characters | & ` < > ( ) ' "
+  # with a backslash.
   #
-  # This differs from Ruby's #escape in that it does not
-  # escape shell variables, e.g. $0.
+  # Unlike Ruby's Shellwords.escape, this leaves other shell
+  # metacharacters alone, including $ (so shell variables still
+  # expand), ; * ? ~ and newlines. It is not safe for untrusted
+  # input: use Shellwords.escape for that.
   def alt_escape(cmdline)
     cmdline.gsub(/([\\\t\| &`<>)('"])/) { |s| '\\' << s }
   end
 
-  unless method_defined?(:escape)
-    def escape(cmdline)
-      cmdline.gsub(/([\\\t\| &`<>)('"])\$/) { |s| '\\' << s }
-    end
-  end
-
   # Escape special character used in DOS-based shells.
   #
   # TODO: How to integrate with rest of system?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: facets
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.0.1
 platform: ruby
 authors:
 - Thomas Sawyer