Module paths 

Workspace path helpers: normalization, canonicalization, containment, safety validation, workspace scopes, and ergonomic extension traits.

The implementation lives in focused submodules; everything is re-exported here so the existing paths:: API is unchanged.

Enums

PathScope

Enumeration describing the conceptual scope of a file path.

Traits

PathExt

Extension trait that adds path normalization and safety methods to Path.

PathResolver

Helper trait that adds path resolution helpers on top of WorkspacePaths.

StrPathExt

Extension trait that adds path-related methods to str.

WorkspacePaths

Provides the root directories an application uses to store data.

Functions

canonicalize

Canonicalize a filesystem path without the Windows \\?\ verbatim prefix.

canonicalize_allow_missing

Canonicalize a path, walking up to find the nearest existing ancestor for new files.

canonicalize_async

Async canonicalize via dunce, using spawn_blocking to avoid blocking the runtime. Equivalent to tokio::fs::canonicalize but without the Windows \\?\ verbatim prefix. Use this in async contexts instead of the sync canonicalize when the path may require I/O.

canonicalize_workspace

Canonicalize a path with fallback to the original path if canonicalization fails.

ensure_path_within_workspace

Ensure a candidate path is inside the workspace root after lexical normalization.

ensure_path_within_workspace_resolved

Ensure a candidate path is inside the workspace root, resolving symlinks component by component.

expand_tilde

Expand a leading ~ or ~/ to the user’s home directory. The function is intentionally forgiving: paths that don’t start with ~ are returned as-is, and when the home directory cannot be determined the original path is preserved so callers can surface a downstream error rather than panicking.

file_name_from_path

Extract the filename from a path, with fallback to the full path.

is_safe_relative_path

Check if a path string is a safe relative path (no traversal, no absolute).

normalize_ascii_identifier

Normalize identifiers to ASCII alphanumerics with lowercase output.

normalize_path

Normalize a path by resolving . and .. components lexically.

resolve_workspace_path

Resolve a path relative to a workspace root and ensure it stays within it.

safe_archive_relative_path

Validate an archive entry name and return it as a destination-relative path.

secure_path

Return a canonicalised absolute path that is guaranteed to reside inside the provided workspace_root. If the path is outside the workspace an error is returned.

validate_no_escaping_symlink_ancestors

Validate every existing path component and reject escaping symlinks.

validate_path_safety

Validates that a path is safe to use. Preventing traversal, absolute system paths, and dangerous characters.

workspace_relative_display

Render a path relative to the workspace when it belongs to that workspace.