Crate cageforge_path 

Shared native path comparison primitives for Cageforge.

These helpers are lexical only. They do not inspect the filesystem or resolve symlinks; a native backend must perform those operations when its enforcement model requires them.

Reading this crate

Use paths_equal and is_within for direct decisions, and NativePathKey when the same identity must be stored in a map or set. contains_parent_traversal validates a lexical input boundary, while normalize_lexical_path exposes supported Windows aliases. The policy, command, and configuration crates build their higher-level rules on these primitives.

⚠️ Independent project

Cageforge is not affiliated with, sponsored by, or endorsed by OpenAI. This crate provides independently authored native path semantics shared by Cageforge libraries.

cageforge-path

cageforge-path centralizes the small set of path comparisons that must agree across Cageforge crates. It treats path components case-sensitively on POSIX systems and case-insensitively on Windows. Windows drive, UNC, verbatim, and supported device aliases share one lexical identity; malformed native strings remain distinct instead of passing through lossy Unicode conversion.

The crate does not access the filesystem, resolve symlinks, or canonicalize paths. Native backends remain responsible for those operations.

When to use it

Use this crate when your own code stores, compares, or validates paths and must agree with Cageforge’s policy and configuration layers. It is especially useful for workspace-root maps, protected metadata paths, and component-aware containment checks.

Do not use it as a filesystem sandbox by itself. It answers lexical questions such as “is this path below that path?”; it does not prove that a file can be opened safely. A native executor must add symlink, junction/reparse-point, mount, and TOCTOU-safe enforcement.

Workspace role

cageforge-path is the shared lexical path-semantics layer.

Crate	Role in the relationship
cageforge-policy	Uses component-aware equality, containment, and path-pattern comparison.
cageforge-command	Validates command working-directory traversal.
cageforge-config	Validates configured workspace-root declarations.
cageforge-policy-compose	Deduplicates and compares effective workspace roots.
cageforge-upstream-review	Validates repository-relative review paths.
cageforge	Re-exports the path model through the application-facing facade.

The helpers define lexical relationships only. A backend still owns filesystem I/O, symlink resolution, canonicalization, and platform capability checks.

Case semantics

The following table is the single path-identity rule shared by the workspace. It is not configurable through TOML or the Rust API.

Value or operation	POSIX (Linux/macOS)	Windows
Absolute and workspace paths	Case-sensitive	Case-insensitive
workspace_roots	Case-sensitive	Case-insensitive
Protected paths such as .git	Case-sensitive	Case-insensitive
Unix socket paths	Case-sensitive	Case-insensitive path comparison
Filesystem glob components	Case-sensitive	Case-insensitive
Environment variable names and filters	Case-insensitive by policy	Case-insensitive by policy
Domain names and domain globs	Case-insensitive by protocol	Case-insensitive by protocol
Profile names and ordinary strings	Exact comparison	Exact comparison

Only the filesystem-related rows use this crate’s native path helpers. The environment and domain rows intentionally have their own portable semantics.

API

• is_within(path, root) checks component-aware containment and does not treat /work-other as a child of /work.
• contains_component_path(path, needle) finds a complete relative component path such as .git without matching a partial component such as .github.
• paths_equal(left, right) compares complete native path components.
• NativePathKey supplies the same equality, hashing, and ordering identity for maps and sets.
• normalize_lexical_path(path) exposes supported native alias normalization without filesystem access.
• strings_equal(left, right) and case_fold(value) expose the same native comparison rule for path-derived glob matching.
• contains_parent_traversal(path) detects lexical .. components.

The helpers are used by policy evaluation, command working-directory validation, policy composition, and the upstream-review tool so those layers cannot silently develop different Windows behavior.

Smallest useful example

use cageforge_path::{is_within, paths_equal, NativePathKey};
use std::path::Path;

let workspace = Path::new("/work/project");
assert!(is_within(Path::new("/work/project/src/lib.rs"), workspace));
assert!(!is_within(Path::new("/work/project-old"), workspace));
assert!(paths_equal(workspace, Path::new("/work/project")));

let _map_key = NativePathKey::new(workspace);

Most applications do not need a direct dependency on this crate: the policy, command, config, and composition crates already use it internally. Depend on it directly when an integration layer has to build its own native path maps or make a comparison before handing values to those crates.

API reference: cageforge-path on docs.rs.

Repository: github.com/m62624/cageforge.

Structs

NativePathKey

A hashable and orderable lexical path identity using native case rules.

Functions

case_fold

Folds a string using the target platform’s path comparison case rules.

components_equal

Compares two path components with the target platform’s path case rules.

contains_component_path

Returns whether path contains needle as a contiguous component path.

contains_parent_traversal

Returns whether a path contains a lexical parent traversal component.

is_within

Returns whether path is the same as or below root by path component.

normalize_lexical_path

Normalizes lexical aliases that the target platform treats as the same path.

paths_equal

Compares two complete paths using the target platform’s path case rules.

strings_equal

Compares path-component strings with the target platform’s path case rules.