stdlib: Update signature of CSV.read

* It takes an IO object as `path` argument
* It returns CSV::Table object when headers option given

refs:

* https://docs.ruby-lang.org/en/3.3/CSV.html#method-c-read
* https://docs.ruby-lang.org/en/3.3/CSV.html#class-CSV-label-Option+headers

Author: tk0miya

stdlib/csv/0/csv.rbs

@@ -2031,7 +2031,8 @@ class CSV < Object
   #     File.write(path, string)
   #     CSV.read(path, headers: true) # => #<CSV::Table mode:col_or_row row_count:4>
   #
-  def self.read: (String path, ?::Hash[Symbol, untyped] options) -> ::Array[::Array[String?]]
+  def self.read: (String | IO path, headers: true | :first_row | Array[untyped] | String, **untyped options) -> ::CSV::Table[CSV::Row]
+               | (String | IO path, ?::Hash[Symbol, untyped] options) -> ::Array[::Array[String?]]
 
   # <!--
   #   rdoc-file=lib/csv.rb

test/stdlib/CSV_test.rb

@@ -35,4 +35,32 @@ def test_foreach
     assert_send_type "(String path, headers: bool, **untyped) -> Enumerator[CSV::Row, void]",
                      CSV, :foreach, path, headers: true, encoding: 'UTF-8'
   end
+
+  def test_read
+    tmpdir = Dir.mktmpdir
+    path = File.join(tmpdir, "example.csv")
+    File.write(path, "a,b,c\n1,2,3\n")
+
+    assert_send_type "(String path, headers: true) -> CSV::Table[CSV::Row]",
+                     CSV, :read, path, headers: true
+    assert_send_type "(IO path, headers: true) -> CSV::Table[CSV::Row]",
+                     CSV, :read, File.open(path), headers: true
+    assert_send_type "(String path, headers: :first_row) -> CSV::Table[CSV::Row]",
+                     CSV, :read, path, headers: :first_row
+    assert_send_type "(IO path, headers: :first_row) -> CSV::Table[CSV::Row]",
+                     CSV, :read, File.open(path), headers: :first_row
+    assert_send_type "(String path, headers: Array[String]) -> CSV::Table[CSV::Row]",
+                     CSV, :read, path, headers: %w[foo bar baz]
+    assert_send_type "(IO path, headers: Array[String]) -> CSV::Table[CSV::Row]",
+                     CSV, :read, File.open(path), headers: %w[foo bar baz]
+    assert_send_type "(String path, headers: String) -> CSV::Table[CSV::Row]",
+                     CSV, :read, path, headers: "foo,bar,baz"
+    assert_send_type "(IO path, headers: String) -> CSV::Table[CSV::Row]",
+                     CSV, :read, File.open(path), headers: "foo,bar,baz"
+
+    assert_send_type "(String path) -> Array[Array[String?]]",
+                     CSV, :read, path
+    assert_send_type "(IO path) -> Array[Array[String?]]",
+                     CSV, :read, File.open(path)
+  end
 end