@@ -27,6 +27,16 @@
   require line, and comment out their line in the aggregator file with
   `# uncommon`.
 
+* Facets must not change what Ruby's own methods do, in the core or the
+  standard library. A Facets method with the same name as one of Ruby's is
+  allowed only if it is compatible, giving Ruby's result for everything
+  Ruby's version accepts (or differing only where Ruby's gives no useful
+  answer, such as raising or returning nil), and it adds something useful.
+  Otherwise Facets gets out of Ruby's way, and the Facets version is either
+  dropped or kept under a new name. Never redefine a method just to copy
+  Ruby's. If Ruby later adds a method Facets already has, the same rule
+  applies.
+
 * Standard libraries that are not extensions of existing standard libraries
   do not have to be divvied up into individual method files. But note that
   full classes and/or modules are less likely to make it into Facets, as
 
@@ -9,10 +9,36 @@ Facets now matches ActiveSupport 8.1 in these cases, which fixes bugs in
 Rails apps that load Facets, and adds the extra options ActiveSupport's
 versions take.
 
+It also stops Facets from changing what Ruby's own methods do. Under a new
+rule, now in CONTRIBUTING.md, a Facets method may share a name with one of
+Ruby's only if it gives Ruby's results and adds something useful. Otherwise
+Facets gets out of Ruby's way.
+
 Changes:
 
 * Bug Fixes
 
+  * `Hash#count`, loaded by `require 'facets'`, gives Ruby's own answers
+    again. Facets' version counted values rather than key-value pairs, which
+    changed Ruby's answer for every library in the program:
+    `{a: 1}.count([:a, 1])` returned 0. To count values, use
+    `hash.values.count(value)`. Until 2027-09-30, `Hash#count` warns when
+    given an argument that can't be a key-value pair, which is how Facets'
+    version was called.
+  * `Array#shelljoin` from `facets/shellwords` is Ruby's own again. Facets'
+    version flattened nested arrays and turned hashes into options, so a
+    value meant as one argument could become several. A web request's
+    parameter can be an array (`?term[]=&term[]=/home`), and with it
+    `['grep', '-r', '--', term, 'public/'].shelljoin` gave
+    `grep -r -- '' /home public/`, which prints every file under `/home`.
+    Ruby's escapes each element as one argument. To turn hashes into
+    options, use `array.shellwords.shelljoin`. Until 2027-09-30,
+    `Array#shelljoin` warns when the array has a hash or an array in it.
+  * `Hash#shellwords`, and so `Hash#shelljoin` and `Array#shellwords`, no
+    longer put quote characters around values. Once the words were escaped
+    with `shelljoin`, the quotes became part of the value:
+    `{name: 'jim'}.shelljoin` passed `"jim"`, quotes included. Each flag and
+    its value is now one plain word, `--name=jim`.
   * `Time.current` uses ActiveSupport's `Time.zone` when it is set. Before,
     when Facets loaded after ActiveSupport, `Time.current` ignored the Rails
     app's time zone and returned the system's local time.
@@ -34,6 +60,29 @@ Changes:
     `"ohaie\nwurld"`. It also raised `NoMethodError` for an empty string.
   * `String#indent` with a negative number and an indent string of more than
     one character removes only whole copies of that string.
+  * `require 'facets/fileutils/ln_r'` replaced Ruby's `FileUtils.link_entry`
+    and an internal method it uses with old copies, so Ruby's own
+    `FileUtils.cp_lr` raised `NameError`. `FileUtils.ln_r` now uses Ruby's
+    `link_entry`, and the file requires `fileutils` itself.
+  * `Pathname#glob` from `facets/pathname/glob` ignored a block; it now gives
+    the block each match, as Ruby's does. With symbol flags, such as
+    `:dotmatch`, it now uses Ruby's glob too, so it works in a directory
+    whose name has glob characters such as `[`, and returns paths in the
+    same form as it does without them. The file requires `pathname` itself.
+  * `Kernel#extend` with no arguments and no block raises `ArgumentError`,
+    as Ruby's does; before, it returned the object. The block form is now a
+    module prepended to `Kernel`, so `ruby -w` no longer warns that `extend`
+    was redefined.
+  * `require 'facets/digest'` raised `LoadError`, because it required a file
+    that had moved. `#salted_digest`'s automatic salt now comes from
+    `SecureRandom` instead of `rand`.
+  * `facets/zlib` no longer defines its own copies of Ruby's `Zlib.inflate`
+    and `Zlib.deflate`. It now requires `zlib` and `stringio` itself;
+    before, `Zlib.compress` raised `NameError` unless they were already
+    loaded.
+  * `OpenStruct#initialize` from `facets/ostruct` calls Ruby's own
+    `initialize` for the hash, instead of a copy of it, and `ruby -w` no
+    longer warns that it was redefined.
 
 * Additions
 
@@ -48,6 +97,12 @@ Changes:
 
 * Changes that can affect existing code
 
+  * `Hash#count(value)` and `Array#shelljoin` no longer do what Facets'
+    versions did; see Bug Fixes. Both warn until 2027-09-30 when called
+    the old way.
+  * `Hash#shellwords` gives `--name=jim` rather than `--name="jim"`. Code
+    that joined the words with spaces into a shell command should use
+    `shelljoin` instead.
   * `Array#split` keeps an empty piece where a match is at either end:
     `[2, 1, 2].split(2)` is `[[], [1], []]`, and `[].split(2)` is `[[]]`.
     Before, empty pieces at the end were dropped.
 
@@ -0,0 +1,47 @@
+## Shellwords
+
+    require 'facets/shellwords'
+
+### Hash#shellwords
+
+Turns a hash into command line flags, one word per flag. A one-letter key
+gives a short flag and a longer key a long one. A value of `true` gives the
+bare flag, and `false` or `nil` leaves the flag out.
+
+    {v: true, debug: true, quiet: false}.shellwords.assert == ['-v', '--debug']
+
+Any other value is joined to its flag with `=`, and an array value repeats
+the flag for each element.
+
+    {name: 'jim', I: ['lib', 'test']}.shellwords.assert ==
+      ['--name=jim', '-I=lib', '-I=test']
+
+The values aren't quoted. Each flag and its value is one word, ready to pass
+to `system(*words)`.
+
+    {name: 'a b'}.shellwords.assert == ['--name=a b']
+
+### Hash#shelljoin
+
+Escapes the flags and joins them into one string for a shell.
+
+    {debug: true, name: 'a b'}.shelljoin.assert == '--debug --name\=a\ b'
+
+The shell splits that string back into the same words.
+
+    Shellwords.split('--debug --name\=a\ b').assert == ['--debug', '--name=a b']
+
+### Array#shellwords
+
+Turns an array in the shape of Ruby method arguments, with options in a hash,
+into command line words. The flags come first.
+
+    ['a', 'b', {d: true}].shellwords.assert == ['-d', 'a', 'b']
+
+To make a command line, join the words with Ruby's own `Array#shelljoin`.
+
+    ['a b', {name: 'jim'}].shellwords.shelljoin.assert == '--name\=jim a\ b'
+
+`Array#shelljoin` itself is Ruby's. It escapes each element as one word and
+doesn't turn hashes into flags, since a value meant as one argument must
+never become several.
@@ -4,6 +4,7 @@
 require 'lemon'
 require 'fileutils'
 require_relative 'quiet_deprecations'
+require_relative 'warning_recorder'
 
 $:.unshift 'lib/rails'
 $:.unshift 'lib/core'
 
@@ -0,0 +1,32 @@
+# Lets a test see the warnings a block raises, including the deprecation
+# warnings that etc/quiet_deprecations.rb would hide.
+#
+#   warnings = WarningRecorder.record { {a: 1}.count(1) }
+#   warnings.size.assert == 1
+#
+# Loaded by etc/test.rb, after quiet_deprecations.rb, so it sees each
+# warning first.
+module WarningRecorder
+  # Run the block and return the warning messages it raised, without
+  # printing them.
+  def self.record
+    @messages = []
+    yield
+    @messages
+  ensure
+    @messages = nil
+  end
+
+  def self.messages
+    @messages
+  end
+
+  def warn(message, *args, **opts)
+    messages = WarningRecorder.messages
+    return super unless messages
+    messages << message
+    nil
+  end
+end
+
+Warning.extend(WarningRecorder)
@@ -1,16 +1,27 @@
 class Hash
 
-  # Like Enumerable#count, but can count hash values.
+  # Ruby's own Hash#count, from Enumerable, counts key-value pairs:
   #
-  #   {:A=>1, :B=>1}.count(1)  #=> 2
+  #   {:A=>1, :B=>1}.count([:A, 1])  #=> 1
   #
-  def count(*value)
-    if value.empty?
-      super()
-    else
-      values.count(*value)
+  # Facets' version used to count values instead, which changed Ruby's
+  # answer for every library in the program. It now returns Ruby's answer,
+  # and warns when given something that can't be a key-value pair, since
+  # that's how the old Facets version was called. To count values, use
+  # `hash.values.count(value)`.
+  #
+  #   {:A=>1, :B=>1}.values.count(1)  #=> 2
+  #
+  # @deprecated Facets no longer changes Hash#count. This warning wrapper is
+  #   scheduled for removal after 2027-09-30.
+  #
+  def count(*args, &block)
+    if args.size == 1 && !(Array === args.first && args.first.size == 2)
+      warn "Facets' Hash#count(value) is deprecated. Hash#count now counts key-value pairs, " \
+           "as Ruby's own does, so this returns 0. To count values, use hash.values.count(value). " \
+           "It will be removed after 2027-09-30.", uplevel: 1
     end
+    super
   end
 
 end
-
 
@@ -1,28 +1,36 @@
-module Kernel
+module Facets
 
-  extend_method = instance_method(:extend)
+  # Prepended to Kernel, so it wraps Ruby's own #extend instead of
+  # replacing it.
+  module KernelExtend
+
+    # Extend an object with a module.
+    #
+    # If a block is given, it will be evaluated into an anonymous
+    # module and used to extend the object.
+    #
+    #   obj = Object.new
+    #
+    #   obj.extend do
+    #     def foo; "foo"; end
+    #   end
+    #
+    #   obj.foo  #=> "foo"
+    #
+    # Without a block it is Ruby's own #extend.
+    #
+    # NOTE: This is one of the few core overrides in Facets.
+    #
+    # @author Trans
+    # @author Marco Otte-Witte (bug fix)
+    def extend(*mods, &blk)
+      return super unless blk
+      super(*mods) unless mods.empty?
+      super(Module.new(&blk))
+    end
 
-  # Extend an object with a module.
-  #
-  # If a block is given, it will be evaluated into an anonymous
-  # module and used to extend the object.
-  #
-  #   obj = Object.new
-  #
-  #   obj.extend do
-  #     def foo; "foo"; end
-  #   end
-  #
-  #   obj.foo  #=> "foo"
-  #
-  # NOTE: This is one of the few core overrides in Facets.
-  #
-  # @author Trans
-  # @author Marco Otte-Witte (bug fix)
-  define_method :extend do |*mod, &blk|
-    extend_method.bind(self).call(*mod) unless mod.empty?
-    extend_method.bind(self).call(Module.new(&blk)) if blk
-    self
   end
 
 end
+
+Kernel.prepend(Facets::KernelExtend)
@@ -1,13 +1,17 @@
 require 'digest'
-require 'facets/string/random_binary'
+require 'securerandom'
 
 module Digest
 
   module Instance
+    # The digest of +str+ followed by +salt+, with the salt appended.
+    # With +salt+ :auto, the salt is +digest_length+ random bytes from
+    # SecureRandom.
+    #
     # CREDIT: Guido De Rosa
     def salted_digest(str='', salt=:auto)
       if salt == :auto
-        salt = String.random_binary(digest_length) 
+        salt = SecureRandom.random_bytes(digest_length)
       end
       digest(str + salt) + salt
     end
 
@@ -1,6 +1,8 @@
+require 'fileutils'
+
 module FileUtils
 
-  unless method_defined?(:ln_r)
+  unless respond_to?(:ln_r)
 
     #
     # Options: noop verbose dereference_root remove_destination
@@ -25,6 +27,9 @@ module FileUtils
     #   FileUtils.ln_r 'src/.', 'dest'     # cp_r('src', 'dest') makes src/dest,
     #                                      # but this doesn't.
     #
+    # It is much like Ruby's own FileUtils.cp_lr, and uses Ruby's
+    # FileUtils.link_entry to make the links.
+    #
     # TODO: Why --remove-destination and not just --force?
     def ln_r(src, dest, options = {})
       fu_output_message "ln -r#{options[:remove_destination] ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
@@ -37,61 +42,7 @@ def ln_r(src, dest, options = {})
     end
     module_function :ln_r
 
-    OPT_TABLE = {} unless const_defined?(:OPT_TABLE)
-    OPT_TABLE['ln_r'] = [:noop, :verbose, :dereference_root, :remove_destination]
-
-    #
-    # Hard links a file system entry +src+ to +dest+.
-    # If +src+ is a directory, this method links its contents recursively.
-    #
-    # Both of +src+ and +dest+ must be a path name.
-    # +src+ must exist, +dest+ must not exist.
-    #
-    # If +dereference_root+ is true, this method dereference tree root.
-    #
-    # If +remove_destination+ is true, this method removes each destination file before copy.
-    #
-    def link_entry(src, dest, dereference_root = false, remove_destination = false)
-      Entry_.new(src, nil, dereference_root).traverse do |ent|
-        destent = Entry_.new(dest, ent.rel, false)
-        File.unlink destent.path if remove_destination && File.file?(destent.path)
-        ent.link destent.path
-      end
-    end
-    module_function :link_entry
-
-    class Entry_ #:nodoc:
-      def link(dest)
-        case
-        when directory?
-          if !File.exist?(dest) and descendant_diretory?(dest, path)
-            raise ArgumentError, "cannot link directory %s to itself %s" % [path, dest]
-          end
-          begin
-            Dir.mkdir dest
-          rescue
-            raise unless File.directory?(dest)
-          end
-        else file?
-          File.link path(), dest
-        end
-      end
-
-      unless const_defined?(:DIRECTORY_TERM)
-        if File::ALT_SEPARATOR
-          DIRECTORY_TERM = "(?=[/#{Regexp.quote(File::ALT_SEPARATOR)}]|\\z)".freeze
-        else
-          DIRECTORY_TERM = "(?=/|\\z)".freeze
-        end
-        SYSCASE = File::FNM_SYSCASE.nonzero? ? "-i" : ""
-      end
-
-      unless method_defined?(:descendant_diretory?)
-        def descendant_diretory?(descendant, ascendant)
-          /\A(?#{SYSCASE}:#{Regexp.quote(ascendant)})#{DIRECTORY_TERM}/ =~ File.dirname(descendant)
-        end
-      end
-    end
+    OPT_TABLE['ln_r'] = [:noop, :verbose, :dereference_root, :remove_destination] if const_defined?(:OPT_TABLE) && !OPT_TABLE.frozen?
 
   end