# Task Plan: `no_std` Refactoring - ABANDONED

## Status: ABANDONED (2025-10-29)

### Decision
This task has been abandoned based on comprehensive feasibility analysis. The `no_std` feature has been removed from the crate.

### Rationale
See `-no_std_increment2_feasibility_analysis.md` for complete analysis. Key findings:
1. **Architectural Incompatibility**: Cannot use `std::path` types (Path, PathBuf, Component) in no_std - they don't exist in core/alloc
2. **False Compatibility**: Current implementation using `extern crate std` creates illusion of no_std support while still requiring std
3. **No Demonstrated Demand**: Zero user requests, no documented use cases
4. **High Cost, Low Value**: Would require 20-40 hours for complete rewrite with limited utility

### Alternative Chosen
**Option 1: Clean Removal** - Remove no_std feature, document std requirement (2 hours)
- Honest and clear to users
- Simpler codebase without conditional compilation
- Focus on actual use cases

### Original Goal (Now Obsolete)
*   ~~Refactor the `pth` crate to be fully compatible with `no_std` environments~~
*   REASON FOR ABANDONMENT: Fundamentally impossible without complete API rewrite
*   **Increment Status:**
    *   ✅ Increment 1: Setup `no_std` foundation and dependencies
    *   ⚫ Increment 2: Replace `std` types with `core` and `alloc` equivalents
    *   ⚫ Increment 3: Conditionally compile all `std`-only APIs
    *   ⚫ Increment 4: Finalization

### Permissions & Boundaries
*   **Mode:** code
*   **Run workspace-wise commands:** false
*   **Add transient comments:** false
*   **Additional Editable Crates:** N/A

### Relevant Context
*   Control Files to Reference:
    *   `module/core/pth/spec.md`
*   Files to Include:
    *   `module/core/pth/Cargo.toml`
    *   `module/core/pth/src/lib.rs`
    *   `module/core/pth/src/as_path.rs`
    *   `module/core/pth/src/try_into_path.rs`
    *   `module/core/pth/src/try_into_cow_path.rs`
    *   `module/core/pth/src/transitive.rs`
    *   `module/core/pth/src/path.rs`
    *   `module/core/pth/src/path/joining.rs`
    *   `module/core/pth/src/path/absolute_path.rs`
    *   `module/core/pth/src/path/canonical_path.rs`
    *   `module/core/pth/src/path/native_path.rs`
    *   `module/core/pth/src/path/current_path.rs`

### Expected Behavior Rules / Specifications
*   The `pth` crate must compile successfully in a `no_std` environment (`cargo check -p pth --features "no_std"`).
*   All `std::` imports must be replaced with `alloc::` or `core::` equivalents, or be conditionally compiled under `#[cfg(not(feature = "no_std"))]`.
*   Functionality dependent on `std::env` or `std::io` that cannot be replicated in `no_std` must be conditionally compiled.
*   Existing functionality under the `default` features must not be broken.

### Crate Conformance Check Procedure
*   **Step 1: Run `no_std` build check.** Execute `timeout 90 cargo check -p pth --features "no_std"`. If this fails, fix the errors before proceeding.
*   **Step 2: Run `std` build check.** Execute `timeout 90 cargo check -p pth`. If this fails, fix the errors before proceeding.
*   **Step 3: Run Tests (Conditional).** Only if Steps 1 and 2 pass, execute `timeout 90 cargo test -p pth --all-targets`. If this fails, fix all test errors before proceeding.
*   **Step 4: Run Linter (Conditional).** Only if Step 3 passes, execute `timeout 120 cargo clippy -p pth --all-features -- -D warnings`.

### Increments
##### Increment 1: Setup `no_std` foundation and dependencies
*   **Goal:** Configure `Cargo.toml` and `lib.rs` to correctly handle the `no_std` feature and its dependencies.
*   **Specification Reference:** N/A
*   **Steps:**
    *   Step 1: In `module/core/pth/Cargo.toml`, modify the `regex` dependency to disable its default features, making it `no_std` compatible.
    *   Step 2: In `module/core/pth/src/lib.rs`, add the `#[cfg(feature = "no_std")] #[macro_use] extern crate alloc;` attribute to make the `alloc` crate available for `no_std` builds.
    *   Step 3: Perform Increment Verification.
    *   Step 4: Perform Crate Conformance Check.
*   **Increment Verification:**
    *   Execute `timeout 90 cargo check -p pth`. This should pass.
    *   Execute `timeout 90 cargo check -p pth --features "no_std"`. This is expected to fail, but we will proceed to the next increment to fix the errors.
*   **Commit Message:** `feat(pth): setup no_std foundation and dependencies`

##### Increment 2: Replace `std` types with `core` and `alloc` equivalents
*   **Goal:** Systematically replace all `std` types that have `core` or `alloc` counterparts across the entire crate.
*   **Specification Reference:** N/A
*   **Steps:**
    *   Step 1: In all relevant `.rs` files (`as_path.rs`, `try_into_path.rs`, `try_into_cow_path.rs`, `transitive.rs`, `path.rs`, `path/*.rs`), add `#[cfg(feature = "no_std")] extern crate alloc;` where needed.
    *   Step 2: In the same files, replace `use std::` with `use core::` for modules like `fmt`, `ops`, `hash`, and `cmp`.
    *   Step 3: In the same files, replace `std::string::String` with `alloc::string::String`, `std::vec::Vec` with `alloc::vec::Vec`, and `std::borrow::Cow` with `alloc::borrow::Cow`.
    *   Step 4: Add `allow` attributes for `clippy::std_instead_of_alloc` and `clippy::std_instead_of_core` at the crate level in `lib.rs` to manage warnings during the transition.
    *   Step 5: Perform Increment Verification.
    *   Step 6: Perform Crate Conformance Check.
*   **Increment Verification:**
    *   Execute `timeout 90 cargo check -p pth --features "no_std"`. The number of errors should be significantly reduced.
    *   Execute `timeout 90 cargo check -p pth`. This should still pass.
*   **Commit Message:** `refactor(pth): replace std types with core and alloc equivalents`

##### Increment 3: Conditionally compile all `std`-only APIs
*   **Goal:** Isolate and gate all functionality that depends on `std`-only modules like `std::io` and `std::env`.
*   **Specification Reference:** N/A
*   **Steps:**
    *   Step 1: In `path/current_path.rs`, wrap the entire module content in `#[cfg(not(feature = "no_std"))]`.
    *   Step 2: In `path.rs`, `path/absolute_path.rs`, `path/canonical_path.rs`, and `path/native_path.rs`, find all functions and `impl` blocks that use `std::io`, `std::env`, or `path::canonicalize`.
    *   Step 3: Wrap these identified functions and `impl` blocks with the `#[cfg(not(feature = "no_std"))]` attribute.
    *   Step 4: In `lib.rs` and `path.rs`, update the `mod_interface!` declarations to conditionally export the gated modules and layers (e.g., `#[cfg(not(feature = "no_std"))] layer current_path;`).
    *   Step 5: Perform Increment Verification.
    *   Step 6: Perform Crate Conformance Check.
*   **Increment Verification:**
    *   Execute `timeout 90 cargo check -p pth --features "no_std"`. This should now pass.
    *   Execute `timeout 90 cargo check -p pth`. This should also pass.
*   **Commit Message:** `refactor(pth): conditionally compile all std-only APIs`

##### Increment 4: Finalization
*   **Goal:** Perform a final, holistic review, run all checks, and ensure the crate is clean and correct.
*   **Specification Reference:** N/A
*   **Steps:**
    *   Step 1: Perform a self-critique of all changes against the requirements.
    *   Step 2: Run the full `Crate Conformance Check Procedure`, including `clippy` and `test`.
    *   Step 3: Remove any temporary `allow` attributes or comments added during the refactoring.
*   **Increment Verification:**
    *   Execute `timeout 90 cargo check -p pth --features "no_std"`. Must pass.
    *   Execute `timeout 90 cargo check -p pth`. Must pass.
    *   Execute `timeout 90 cargo test -p pth --all-targets`. Must pass.
    *   Execute `timeout 120 cargo clippy -p pth --all-features -- -D warnings`. Must pass.
*   **Commit Message:** `chore(pth): finalize no_std refactoring`

### Task Requirements
*   The `pth` crate must be fully `no_std` compatible.
*   All `std` dependencies must be removed or conditionally compiled.

### Project Requirements
*   (Inherited from workspace `Cargo.toml`)

### Assumptions
*   `alloc` is available in `no_std` environments.
*   `camino` and `serde` crates are `no_std` compatible or can be conditionally compiled as needed.

### Out of Scope
*   Adding `no_std` specific tests. The focus is on making the code compile.
*   Implementing new features in `pth`.

### External System Dependencies
*   N/A

### Notes & Insights
*   This plan prioritizes broad, sweeping changes by concern, which is more efficient for this type of refactoring.
*   The key challenge is correctly identifying and gating all code that relies on the standard library's IO and environment capabilities.

### Changelog
*   [Initial] Plan created.
*   [Revision 1] Plan streamlined to 4 increments, focusing on changes by concern for greater efficiency.
*   [Revision 2 | 2025-07-01 12:33 UTC] Updated Crate Conformance Check Procedure to include `cargo test`. Added "Perform Crate Conformance Check" step to all increments.
*   [Revision 3 | 2025-07-01 12:34 UTC] Marked Increment 1 as in progress (⏳).
*   [Increment 1 | 2025-07-01 12:35 UTC] Modified `Cargo.toml` to disable default features for `regex` dependency.
*   [Increment 1 | 2025-07-01 12:35 UTC] Added `#[cfg(feature = "no_std")] #[macro_use] extern crate alloc;` to `lib.rs`.
*   [Increment 1 | 2025-07-01 12:36 UTC] Removed duplicate `extern crate alloc;` from `lib.rs`.