WorkspacePath

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Workspace

WorkspacePath Class

Canonicalization helpers for IWorkspace paths.

public static class WorkspacePath

Inheritance System.Object 🡒 WorkspacePath

Remarks

IWorkspace is a logical, rooted key/value store: a path identifies a single file regardless of how the caller spells it. Without canonicalization, the strings kb/foo.md, ./kb/foo.md, kb//foo.md, kb/./foo.md, /kb/foo.md, and kb/foo.md/ would all be distinct keys despite referring to the same logical file. This class defines the canonical form every implementation MUST produce before keying or comparing paths.

The canonical form is structural only — it does NOT lower-case or re-encode the string. Path equality is performed by PathComparer, which is case-insensitive (System.StringComparer.OrdinalIgnoreCase). Implementations MUST use this comparer (or one with equivalent semantics) when storing or comparing canonicalized paths.

Use Canonicalize(string) for paths that identify a file (the common case). Use CanonicalizeDirectory(string) for paths that identify a directory (e.g., the directory argument to ListDirectory(string, int)) — the directory variant accepts root-equivalent inputs ("", ".", "/", etc.) and returns the workspace-root sentinel (""), whereas the file variant rejects them.

Invalid paths throw System.ArgumentNullException or System.ArgumentException directly. They are NOT wrapped in Fail(Exception). Fail(Exception) is reserved for valid paths where the workspace operation legitimately fails (file missing, compare-exchange mismatch, etc.).

Properties

WorkspacePath.PathComparer Property

The System.StringComparer implementations MUST use for path equality. Case-insensitive, ordinal — matches the dominant file-system convention on Windows and macOS, and aligns with the historical InMemoryWorkspace behavior.

public static System.StringComparer PathComparer { get; }

Property Value

System.StringComparer

Methods

WorkspacePath.Canonicalize(string) Method

Canonicalizes a workspace file path.

public static string Canonicalize(string path);

Parameters

path System.String

The path to canonicalize.

Returns

System.String
The canonical form of path.

Exceptions

System.ArgumentNullException
path is null.

System.ArgumentException
path is empty, whitespace-only, contains a .. segment, or canonicalizes to the empty string.

Example

WorkspacePath.Canonicalize("kb/foo.md")        // → "kb/foo.md"
WorkspacePath.Canonicalize("./kb/foo.md")      // → "kb/foo.md"
WorkspacePath.Canonicalize("kb//foo.md")       // → "kb/foo.md"
WorkspacePath.Canonicalize(@"kb\foo.md")       // → "kb/foo.md"
WorkspacePath.Canonicalize("/kb/foo.md/")      // → "kb/foo.md"
WorkspacePath.Canonicalize("kb/../foo.md")     // throws ArgumentException
WorkspacePath.Canonicalize("/")                // throws ArgumentException

Remarks

Rules applied, in order: 1. Outer whitespace is trimmed (segment-internal whitespace is preserved). 2. Backslashes (\) are replaced with forward slashes (/). 3. . segments are dropped (so ./kb/foo becomes kb/foo). 4. Empty segments are collapsed (so kb//foo becomes kb/foo). 5. Leading and trailing slashes are stripped (so /kb/foo/ becomes kb/foo).

The following inputs are rejected: - null → System.ArgumentNullException. - Empty or whitespace-only string → System.ArgumentException. - Any segment exactly equal to .. (parent traversal) → System.ArgumentException. Filenames that merely contain.. as a substring (e.g., version..draft.md) are accepted. - Inputs that canonicalize to the empty string ("/", "//", ".", "./", "/./", …) → System.ArgumentException. Use CanonicalizeDirectory(string) if you need to express the workspace root.

WorkspacePath.CanonicalizeDirectory(string) Method

Canonicalizes a workspace directory path. Use this for the directory argument to ListDirectory(string, int) and any other API that accepts a directory.

public static string CanonicalizeDirectory(string directory);

Parameters

directory System.String

The directory path to canonicalize.

Returns

System.String
The canonical form of directory, or the empty string for root-equivalent inputs.

Exceptions

System.ArgumentNullException
directory is null.

System.ArgumentException
directory contains a .. segment.

Example

WorkspacePath.CanonicalizeDirectory("")        // → ""
WorkspacePath.CanonicalizeDirectory(".")       // → ""
WorkspacePath.CanonicalizeDirectory("/")       // → ""
WorkspacePath.CanonicalizeDirectory("./src")   // → "src"
WorkspacePath.CanonicalizeDirectory("src/")    // → "src"
WorkspacePath.CanonicalizeDirectory("src//")   // → "src"
WorkspacePath.CanonicalizeDirectory("../src")  // throws ArgumentException

Remarks

Same rules as Canonicalize(string), with one difference: root-equivalent inputs ("", whitespace-only, ".", "./", "/", "//", "/./", …) all return the empty string, representing the workspace root. Canonicalize(string) rejects these.

null still throws System.ArgumentNullException, and segment-exact .. still throws System.ArgumentException.