feature: Accept plain String paths on IO/FileSystem

[xerial]

Summary

• IO.readString, IO.writeString, and the rest of the IO / FileSystem surface now accept a plain String path in addition to IOPath, removing the IO.path(...) wrapper from the common case.
• Same treatment for Gzip.compressFile / decompressFile, Zip.create / extract / list, and IOWatch.watch.
• IO.path(...) stays — it remains the canonical way to build an IOPath for composition (/), normalization, or part-queries (fileName, parent, extension).
• Docs (docs/core/filesystem.md, docs/core/io.md, docs/uni-walkthrough.md) rewritten to show plain-string usage. The doc note narrows the claim so it doesn't overpromise for the remaining Option[IOPath] cases (e.g. createTempFile's directory parameter).

Why overloads, not given Conversion[String, IOPath]?

A Scala 3 Conversion still requires import scala.language.implicitConversions at each call site, which defeats the simpler-docs goal. Overloads are zero-ceremony and IDE-discoverable; the cost is ~30 one-line delegates concentrated in FileSystemBase.

Example

// Before
val content = IO.readString(IO.path("data.txt"))
IO.writeString(IO.path("out.txt"), "hello")

// After
val content = IO.readString("data.txt")
IO.writeString("out.txt", "hello")

// IO.path is still there when you need IOPath operations
val path = IO.path("/home/user") / "project" / "README.md"
println(path.fileName) // "README.md"

Test plan

• ./sbt scalafmtAll
• ./sbt coreJVM/test uniJVM/test — 1613 tests pass, 4 pending
• ./sbt uniJS/testOnly *IO* — 28 JS tests pass
• ./sbt coreJS/compile coreNative/compile uniJS/test:compile uniNative/test:compile
• Added IOFileSystemTest cases covering read/write, write modes, list/delete, copy/move with String paths
• Added GzipTest, ZipTest, and IOWatchJvmTest cases exercising the new String overloads

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces String-accepting overloads for path-based operations in the IO, FileSystem, Gzip, and Zip APIs, allowing for more concise code by removing the requirement for explicit IOPath wrapping. The update includes extensive documentation revisions and new test cases to validate the overloads. Feedback identifies a redundant DummyImplicit parameter in the Zip.create method that should be removed to clean up the API signature.

[gemini-code-assist]

The DummyImplicit parameter appears to be redundant here. Since the first parameter target is a String (whereas the original method takes an IOPath), the erased signatures of the two create overloads are already distinct (create(String, Seq) vs create(IOPath, Seq)). DummyImplicit is typically only necessary when the signatures are identical after erasure, which usually happens when only the generic type parameters differ.

  def create(target: String, sources: Seq[String]): Unit = create(

[xerial]

Good catch — removed in 9214c18. Verified the two overloads compile and resolve correctly on JVM/JS/Native because the first parameter keeps the erased signatures distinct (IOPath vs String).

[xerial]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces String-accepting overloads for path-based operations across the IO, FileSystem, Gzip, and Zip APIs, reducing the need for explicit IOPath wrapping. The changes include extensive updates to documentation and examples to reflect the simplified usage, along with new test cases verifying the overloads. Regarding the implementation in Zip.scala, it is recommended to use the @targetName annotation instead of DummyImplicit to resolve JVM erasure clashes, as it is the idiomatic Scala 3 approach.

[gemini-code-assist]

The use of DummyImplicit is a valid way to resolve the JVM erasure clash between Seq[String] and Seq[IOPath]. However, in Scala 3, using the @targetName annotation is generally preferred for this purpose as it is more explicit and doesn't introduce an extra parameter at the bytecode level.