From df3ce9890ae475f7bbd40cc2655139a4f9fde5b0 Mon Sep 17 00:00:00 2001
From: HoneyryderChuck <cardoso_tiago@hotmail.com>
Date: Mon, 12 Jan 2026 10:15:05 +0000
Subject: [PATCH] add extra kwarg options for File#initialize and derivatives

this adds the missing kwargs (known as "Open options" and "Encoding
options" in the docs) signatures to the following methods, which
implemented the same derivative signature:

* File#initialize
* File.open
* Pathname#open
---
 core/file.rbs                | 75 ++++++++++++++++++++++++++++++++++--
 core/pathname.rbs            | 47 +++++++++++++++++++++-
 test/stdlib/File_test.rb     |  9 +++++
 test/stdlib/Pathname_test.rb |  3 ++
 4 files changed, 129 insertions(+), 5 deletions(-)

diff --git a/core/file.rbs b/core/file.rbs
index c77952cf2..5371d76ce 100644
--- a/core/file.rbs
+++ b/core/file.rbs
@@ -847,7 +847,30 @@ class File < IO
   # *   [Open Options](rdoc-ref:IO@Open+Options).
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
-  def initialize: (path | int file_name, ?string | int mode, ?int perm) -> void
+  def initialize: (
+    path | int file_name,
+    ?string | int mode,
+    ?int perm,
+  # open options
+    ?mode: Integer | String,
+    ?flags: Integer,
+    ?external_encoding: encoding,
+    ?internal_encoding: encoding,
+    ?encoding: encoding,
+    ?textmode: boolish,
+    ?binmode: boolish,
+    ?autoclose: boolish,
+    ?path: path,
+  # encoding options
+    ?invalid: :replace | nil,
+    ?undef: :replace | nil,
+    ?replace: String | nil,
+    ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+    ?xml: :text | :attr | nil,
+    ?cr_newline: bool,
+    ?crlf_newline: bool,
+    ?universal_newline: bool
+  ) -> void
 
   # <!--
   #   rdoc-file=file.c
@@ -1407,8 +1430,54 @@ class File < IO
   # With a block given, calls the block with the File object and returns the
   # block's value.
   #
-  def self.open: (path | int file_name, ?string | int mode, ?int perm) -> instance
-               | [T] (path | int file_name, ?string | int mode, ?int perm) { (File) -> T } -> T
+  def self.open: (
+    path | int file_name,
+    ?string | int mode,
+    ?int perm,
+  # open options
+    ?mode: Integer | String,
+    ?flags: Integer,
+    ?external_encoding: encoding,
+    ?internal_encoding: encoding,
+    ?encoding: encoding,
+    ?textmode: boolish,
+    ?binmode: boolish,
+    ?autoclose: boolish,
+    ?path: path,
+  # encoding options
+    ?invalid: :replace | nil,
+    ?undef: :replace | nil,
+    ?replace: String | nil,
+    ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+    ?xml: :text | :attr | nil,
+    ?cr_newline: bool,
+    ?crlf_newline: bool,
+    ?universal_newline: bool
+  ) -> instance
+               | [T] (
+      path | int file_name,
+      ?string | int mode,
+      ?int perm,
+  # open options
+      ?mode: Integer | String,
+      ?flags: Integer,
+      ?external_encoding: encoding,
+      ?internal_encoding: encoding,
+      ?encoding: encoding,
+      ?textmode: boolish,
+      ?binmode: boolish,
+      ?autoclose: boolish,
+      ?path: path,
+  # encoding options
+      ?invalid: :replace | nil,
+      ?undef: :replace | nil,
+      ?replace: String | nil,
+      ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+      ?xml: :text | :attr | nil,
+      ?cr_newline: bool,
+      ?crlf_newline: bool,
+      ?universal_newline: bool
+    ) { (File) -> T } -> T
 
   # <!--
   #   rdoc-file=file.c
diff --git a/core/pathname.rbs b/core/pathname.rbs
index 0a5992f6c..c88da5a45 100644
--- a/core/pathname.rbs
+++ b/core/pathname.rbs
@@ -838,8 +838,51 @@ class Pathname
   # -->
   # See `File.open`.  Opens the file for reading or writing.
   #
-  def open: (?string | int mode, ?int perm) -> File
-          | [T] (?string | int mode, ?int perm) { (File) -> T } -> T
+  def open: (
+      ?string | int mode,
+      ?int perm,
+  # open options
+      ?flags: Integer,
+      ?external_encoding: encoding,
+      ?internal_encoding: encoding,
+      ?encoding: encoding,
+      ?textmode: boolish,
+      ?binmode: boolish,
+      ?autoclose: boolish,
+      ?path: path,
+  # encoding options
+      ?invalid: :replace | nil,
+      ?undef: :replace | nil,
+      ?replace: String | nil,
+      ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+      ?xml: :text | :attr | nil,
+      ?cr_newline: bool,
+      ?crlf_newline: bool,
+      ?universal_newline: bool
+    ) -> File
+          | [T] (
+      ?string | int mode,
+      ?int perm,
+  # open options
+      ?mode: Integer | String,
+      ?flags: Integer,
+      ?external_encoding: encoding,
+      ?internal_encoding: encoding,
+      ?encoding: encoding,
+      ?textmode: boolish,
+      ?binmode: boolish,
+      ?autoclose: boolish,
+      ?path: path,
+  # encoding options
+      ?invalid: :replace | nil,
+      ?undef: :replace | nil,
+      ?replace: String | nil,
+      ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+      ?xml: :text | :attr | nil,
+      ?cr_newline: bool,
+      ?crlf_newline: bool,
+      ?universal_newline: bool
+    ) { (File) -> T } -> T
 
   # <!--
   #   rdoc-file=pathname_builtin.rb
diff --git a/test/stdlib/File_test.rb b/test/stdlib/File_test.rb
index 27042d88d..0f18b74a8 100644
--- a/test/stdlib/File_test.rb
+++ b/test/stdlib/File_test.rb
@@ -29,6 +29,10 @@ def test_new
                      File, :new, File.expand_path(__FILE__), "r", 0644
     assert_send_type "(String, String, ToInt) -> File",
                      File, :new, File.expand_path(__FILE__), "r", ToInt.new(0644)
+    assert_send_type "(String, mode: String) -> File",
+                     File, :new, File.expand_path(__FILE__), mode: "r"
+    assert_send_type "(String, mode: Integer) -> File",
+                     File, :new, File.expand_path(__FILE__), mode: File::RDONLY
   end
 
   def test_open
@@ -56,6 +60,11 @@ def test_open
                      File, :open, File.expand_path(__FILE__), "r", ToInt.new(0644)
     assert_send_type "(String) { (File) -> String } -> String",
                      File, :open, File.expand_path(__FILE__) do |file| file.read end
+    assert_send_type "(String, mode: String) -> File",
+                     File, :open, File.expand_path(__FILE__), mode: "r"
+    assert_send_type "(String, mode: Integer) -> File",
+                     File, :open, File.expand_path(__FILE__), mode: File::RDONLY
+
   end
 
   def test_absolute_path
diff --git a/test/stdlib/Pathname_test.rb b/test/stdlib/Pathname_test.rb
index 656a53efd..50de3fcc2 100644
--- a/test/stdlib/Pathname_test.rb
+++ b/test/stdlib/Pathname_test.rb
@@ -479,6 +479,9 @@ def test_open
                        path, :open, 'r', 0644
       assert_send_type '() { (File) -> true} -> true',
                        path, :open do true end
+      assert_send_type "(String, binmode: bool) -> File",
+                       path, :open, 'r', binmode: true
+
     end
   end