[API Proposal]: File content helpers so build scripts stay in one vocabulary

[dennisdoomen]

Background and motivation

Pathy covers building and inspecting paths and a few file system operations, but the moment you want to read or write the file you have just located, you switch to File.ReadAllText(path.ToString()). In a build script or a test that mixes both styles, this is a constant, jarring context switch, and it means the path has to be converted back to a string over and over. Thin wrappers would let a script speak one vocabulary from start to finish.

API Proposal

namespace Pathy
{
    public static class ChainablePathExtensions
    {
        public static string ReadAllText(this ChainablePath path);
        public static string ReadAllText(this ChainablePath path, Encoding encoding);
        public static string[] ReadAllLines(this ChainablePath path);
        public static IEnumerable<string> ReadLines(this ChainablePath path);
        public static byte[] ReadAllBytes(this ChainablePath path);

        public static void WriteAllText(this ChainablePath path, string contents);
        public static void WriteAllText(this ChainablePath path, string contents, Encoding encoding);
        public static void WriteAllLines(this ChainablePath path, IEnumerable<string> contents);
        public static void WriteAllBytes(this ChainablePath path, byte[] bytes);
        public static void AppendAllText(this ChainablePath path, string contents);

        public static FileStream OpenRead(this ChainablePath path);
        public static FileStream OpenWrite(this ChainablePath path);
    }
}

API Usage

var version = (ChainablePath.Current / "version.txt").ReadAllText().Trim();

(artifacts / "manifest.json").WriteAllText(JsonSerializer.Serialize(manifest));

foreach (var line in (logs / "build.log").ReadLines())
{
    ...
}

Alternative Designs

• Do nothing and let callers use File.* with an implicit conversion to string. This already works, so the proposal is purely about ergonomics and consistency.
• Ship these in a separate Pathy.IO package to keep the core surface small. Worth considering, although unlike globbing these wrappers need no extra dependency.

Risks

This grows the API surface noticeably for what is mostly convenience, and it invites scope creep toward wrapping all of System.IO. A clear boundary is needed. There is also a question of whether the write methods should create missing parent directories; doing so silently would differ from File.WriteAllText and could surprise people.