code_archive.txt

/*
archive of functions and code from project's misty past...
oh, those were the days...
*/

/// Recursively collects file system entries from directory and all subdirectories
///
/// # Purpose
/// Traverses a directory tree starting from the specified root directory,
/// collecting all files and subdirectories for searching operations.
///
/// # Critical Implementation Note
/// This function MUST receive the actual directory to search, not assume
/// any particular directory. The caller is responsible for providing the
/// correct starting directory based on the application's navigation state.
///
/// # Arguments
/// * `start_directory` - The root directory from which to start collecting.
///                       This should be the user's current navigation location,
///                       NOT the process working directory.
///
/// # Common Mistake
/// DO NOT use std::env::current_dir() here or in calling code.
/// The process working directory is NOT the same as the file manager's
/// current navigation directory.
fn collect_entries_recursive(
    &self,
    start_directory: &Path,  // Must be the actual navigation directory
) -> Result<Vec<FileSystemEntry>> {
    let mut all_entries = Vec::new();
    let mut directories_to_process = vec![start_directory.to_path_buf()];

    while let Some(current_dir) = directories_to_process.pop() {
        // Try to read the current directory, skip if we can't
        let dir_entries = match fs::read_dir(&current_dir) {
            Ok(entries) => entries,
            Err(_) => continue, // Skip directories we can't read
        };

        for entry_result in dir_entries {
            // Skip entries we can't read
            let entry = match entry_result {
                Ok(e) => e,
                Err(_) => continue,
            };

            // Get metadata, skip if we can't read it
            let metadata = match entry.metadata() {
                Ok(m) => m,
                Err(_) => continue,
            };

            // Get the file name as a string, skip if invalid
            let file_name = match entry.file_name().into_string() {
                Ok(name) => name,
                Err(_) => continue,
            };

            let path = entry.path();

            // Add to entries list
            all_entries.push(FileSystemEntry {
                file_system_item_name: file_name,
                file_system_item_path: path.clone(),
                file_system_item_size_in_bytes: metadata.len(),
                file_system_item_last_modified_time: metadata.modified()
                    .unwrap_or(SystemTime::UNIX_EPOCH),
                is_directory: metadata.is_dir(),
            });

            // If it's a directory, add it to the processing queue
            if metadata.is_dir() {
                directories_to_process.push(path);
            }
        }
    }

    Ok(all_entries)
}


    // Pass the correct is_grep flag to display function
    display_extended_search_results(&search_results).map_err(|e| {
        eprintln!("Failed to display search results: {}", e);
        FileFantasticError::Io(e)
    })?;

    // Wait for user to select from results or press enter to continue
    print!("\nEnter number to select or press Enter to continue: ");
    io::stdout().flush().map_err(|e| {
        eprintln!("Failed to flush stdout: {}", e);
        FileFantasticError::Io(e)
    })?;

    let mut selection = String::new();
    io::stdin().read_line(&mut selection).map_err(|e| {
        eprintln!("Failed to read input: {}", e);
        FileFantasticError::Io(e)
    })?;

/// simple, works, no pagination
/// Displays search results with appropriate formatting based on search type
///
/// # Purpose
/// Presents search results to the user in a readable tabular format,
/// automatically detecting the search type from the result enum and displaying
/// the appropriate format for each type.
///
/// # Arguments
/// * `results` - Slice of UnifiedSearchResult items to display
///               The enum variant determines the display format
///
/// # Returns
/// * `io::Result<()>` - Ok(()) on successful display, or an IO error if terminal
///                       output operations fail
///
/// # Display Formats
///
/// ## Fuzzy Name Search Format:
/// Shows the Levenshtein distance to help users understand match quality
/// ```text
/// Search Results (Fuzzy Match)
/// #     Name                                     Distance
/// -------------------------------------------------------
/// 1     example.txt                              1
/// 2     example2.doc                             2
/// ```
///
/// ## Grep Content Search Format:
/// Shows the line number and content for each match
/// ```text
/// Search Results (Content Match)
/// #     File                                     Line    Content
/// --------------------------------------------------------------
/// 1     src/main.rs                              42      // TODO: implement
/// 2     src/lib.rs                               15      // TODO: document
/// ```
///
/// # Implementation Details
/// - Clears the terminal screen before displaying results for clean presentation
/// - Truncates long filenames to maintain table alignment (max 38 characters)
/// - Automatically detects search type from enum variant
/// - Shows "No matches found" message for empty result sets
///
/// # User Interface Flow
/// After displaying results, the user can:
/// - Enter a number to select and navigate to that file
/// - Press Enter to continue without selection
///
/// # Error Handling
/// - Returns IO errors from terminal output operations
/// - Handles empty result sets gracefully with informative message
pub fn display_extended_search_results(
    results: &[UnifiedSearchResult],
) -> io::Result<()> {  // Note: removed is_grep parameter - not needed with enum

    // Handle empty results with user-friendly message
    if results.is_empty() {
        println!("No matches found");
        return Ok(());
    }

    // Clear screen for clean display
    print!("\x1B[2J\x1B[1;1H");

    // Determine search type from first result and display accordingly
    match &results[0] {
        UnifiedSearchResult::Grep(_) => {
            // Display header for grep results
            println!("\nContent Search Results (try: -g -r -c)"); // -fg --fuzzygrep
            println!("{:<5} {:<30} {:<7} {}", "#", "File", "Line", "Content");
            println!("{}", "-".repeat(80));

            // Display each grep result
            for result in results {
                if let UnifiedSearchResult::Grep(grep_result) = result {
                    // Truncate filename if too long
                    let display_name = if grep_result.file_name.len() > 28 {
                        format!("{}...", &grep_result.file_name[..25])
                    } else {
                        grep_result.file_name.clone()
                    };

                    // Truncate content if too long
                    let display_content = if grep_result.line_content.len() > 35 {
                        format!("{}...", &grep_result.line_content[..32])
                    } else {
                        grep_result.line_content.clone()
                    };

                    println!(
                        "{:<5} {:<30} {:<7} {}",
                        grep_result.display_index,
                        display_name,
                        grep_result.line_number,
                        display_content
                    );
                }
            }
        }

        UnifiedSearchResult::Fuzzy(_) => {
            // Display header for fuzzy search results
            println!("\nFuzzy Name Search Results (try: --grep --recursive --case-sensitive)");
            println!("{:<5} {:<40} {:<10}", "#", "Name", "Distance");
            println!("{}", "-".repeat(55));

            // Display each fuzzy result
            for result in results {
                if let UnifiedSearchResult::Fuzzy(fuzzy_result) = result {
                    // Truncate filename if too long
                    let display_name = if fuzzy_result.item_name.len() > 38 {
                        format!("{}...", &fuzzy_result.item_name[..35])
                    } else {
                        fuzzy_result.item_name.clone()
                    };

                    println!(
                        "{:<5} {:<40} {:<10}",
                        fuzzy_result.display_index,
                        display_name,
                        fuzzy_result.distance
                    );
                }
            }
        }
    }

    Ok(())
}


// /// Creates archive directory if it doesn't exist
// ///
// /// # Purpose
// /// Ensures that an "archive" subdirectory exists in the specified parent directory,
// /// creating it if necessary. This directory is used to store copies of files
// /// when avoiding overwrites.
// ///
// /// # Arguments
// /// * `parent_directory` - The directory where the archive folder should exist
// ///
// /// # Returns
// /// * `Result<PathBuf>` - Absolute path to the archive directory, or error
// ///
// /// # Error Conditions
// /// - IO errors when creating the directory
// /// - Permission denied when writing to parent directory
// /// - Invalid parent directory path
// ///
// /// # Archive Directory Structure
// /// ```text
// /// parent_directory/
// /// ├── existing_files...
// /// └── archive/          <- Created by this function
// ///     ├── file1_timestamp.ext
// ///     └── file2_timestamp.ext
// /// ```
// ///
// /// # Example
// /// ```rust
// /// let current_dir = PathBuf::from("/home/user/documents");
// /// match ensure_archive_directory_exists(&current_dir) {
// ///     Ok(archive_path) => {
// ///         // archive_path is "/home/user/documents/archive"
// ///         println!("Archive directory ready: {}", archive_path.display());
// ///     },
// ///     Err(e) => eprintln!("Failed to create archive directory: {}", e),
// /// }
// /// ```
// fn ensure_archive_directory_exists(parent_directory: &PathBuf) -> Result<PathBuf> {
//     let archive_directory_path = parent_directory.join("archive");

//     // Check if archive directory already exists
//     if !archive_directory_path.exists() {
//         // Create the archive directory
//         fs::create_dir(&archive_directory_path).map_err(|e| {
//             match e.kind() {
//                 io::ErrorKind::PermissionDenied => {
//                     FileFantasticError::PermissionDenied(archive_directory_path.clone())
//                 },
//                 _ => FileFantasticError::Io(e)
//             }
//         })?;

//         println!("Created archive directory: {}", archive_directory_path.display());
//     }

//     // Verify it's actually a directory
//     if !archive_directory_path.is_dir() {
//         return Err(FileFantasticError::InvalidName(
//             format!("Archive path exists but is not a directory: {}",
//                    archive_directory_path.display())
//         ));
//     }

//     Ok(archive_directory_path)
// }


// /// Opens a file in a tmux split pane
// ///
// /// # Arguments
// /// * `editor` - The editor command to use
// /// * `file_path` - Path to the file to open
// /// * `split_type` - Either "-v" for vertical or "-h" for horizontal split
// ///
// /// # Returns
// /// * `Result<()>` - Success or error
// ///
// /// # Prerequisites
// /// - tmux must be installed and available
// /// - Must be running inside a tmux session
// ///
// /// # Behavior
// /// Creates a new tmux pane and opens the editor in it
// /// The pane closes automatically when the editor exits
// fn open_in_tmux_split(editor: &str, file_path: &PathBuf, split_type: &str) -> Result<()> {
//     // Check if the specified editor is available
//     if !is_command_available(editor) {
//         return Err(FileFantasticError::EditorLaunchFailed(format!(
//             "Editor '{}' is not available on this system",
//             editor
//         )));
//     }

//     // Build the command to run in the new split
//     let editor_command = format!("{} {}", editor, file_path.to_string_lossy());

//     // Create the tmux split with the editor
//     let output = std::process::Command::new("tmux")
//         .args([
//             "split-window",
//             split_type, // "-v" for vertical, "-h" for horizontal
//             &editor_command,
//         ])
//         .output()
//         .map_err(|e| {
//             eprintln!("Failed to create tmux split: {}", e);
//             FileFantasticError::Io(e)
//         })?;

//     if output.status.success() {
//         println!(
//             "Opened {} in tmux {} split",
//             editor,
//             if split_type == "-v" {
//                 "vertical"
//             } else {
//                 "horizontal"
//             }
//         );
//         Ok(())
//     } else {
//         Err(FileFantasticError::EditorLaunchFailed(format!(
//             "Failed to create tmux split: {}",
//             String::from_utf8_lossy(&output.stderr)
//         )))
//     }
// }



/// Parses special flags from user input for headless mode, tmux splits, and CSV analysis
///
/// # Arguments
/// * `input` - The user input string
///
/// # Returns
/// * `Option<(String, String)>` - Some((editor, flag)) if a special flag is found, None otherwise
///
/// # Supported Flags
/// * `-h` or `--headless` - Open in current terminal
/// * `-vsplit` or `--vertical-split-tmux` - Open in vertical tmux split
/// * `-hsplit` or `--horizontal-split-tmux` - Open in horizontal tmux split
/// * `-rc` or `--rows-and-columns` - Analyze CSV file before opening (CSV files only)
///
/// # Examples
/// * "vim -h" -> Some(("vim", "-h"))
/// * "nano -rc" -> Some(("nano", "-rc"))
/// * "code -h -rc" -> Some(("code", "-h -rc")) // Combined flags preserved
fn parse_special_flags(input: &str) -> Option<(String, String)> {
    let flags = [
        "-h",
        "--headless",
        "-vsplit",
        "--vertical-split-tmux",
        "-hsplit",
        "--horizontal-split-tmux",
        "-rc",
        "--rows-and-columns",
    ];

    // Check if input contains any special flags
    let mut found_flags = Vec::new();
    let mut editor_parts = Vec::new();

    let parts: Vec<&str> = input.split_whitespace().collect();

    for part in &parts {
        if flags.contains(&part.as_ref()) {
            found_flags.push(part.to_string());
        } else {
            editor_parts.push(part.to_string());
        }
    }

    if !found_flags.is_empty() {
        let editor = editor_parts.join(" ");
        let flags_str = found_flags.join(" ");
        Some((editor, flags_str))
    } else {
        None
    }
}

        // // Now handle the other flags with the appropriate file
        // // Extract the primary action flag (for headless/tmux)
        // let primary_flag = if flags.contains("-h") || flags.contains("--headless") {
        //     "--headless"
        // } else if flags.contains("-vsplit") || flags.contains("--vertical-split-tmux") {
        //     "-vsplit"
        // } else if flags.contains("-hsplit") || flags.contains("--horizontal-split-tmux") {
        //     "-hsplit"
        // } else if flags.contains("-rc") || flags.contains("--rows-and-columns") {
        //     // If only -rc flag, open normally (no special terminal mode)
        //     ""
        // } else {
        //     ""
        // };



    /// Interactive interface to add a file to the file stack
    ///
    /// # Purpose
    /// Provides a simple interactive interface for adding files to the file stack.
    /// Shows the current directory listing and prompts user to select a file by number.
    /// Works with the current page view only, utilizing existing navigation state.
    ///
    /// # Arguments
    /// * `nav_state` - Current navigation state with lookup table for numbered selection
    /// * `current_directory_entries` - Current directory entries to display for selection (current page only)
    /// * `current_directory_path` - Current directory path for display context
    ///
    /// # Returns
    /// * `Result<()>` - Success or error with context
    ///
    /// # User Interface Workflow
    ///
    /// ## Step 1: Display Current View
    /// - Show current directory contents with numbered items (same as main navigation)
    /// - This respects current filter and pagination state
    ///
    /// ## Step 2: Selection Prompt
    /// - User selects item by number (same interface as navigation)
    /// - Can cancel with 'b' for back
    ///
    /// ## Step 3: Validation
    /// - Verify selected item exists in lookup table
    /// - Ensure selected item is a file (not a directory)
    ///
    /// ## Step 4: Add to Stack
    /// - Add file path to the file stack
    /// - Display confirmation with updated stack count
    ///
    /// # Example Interaction
    /// ```text
    /// Current Directory: /home/user/documents
    ///
    /// Num  Name                    Size     Modified
    /// ------------------------------------------------
    ///  1)  folder1/               -        14:30
    ///  2)  document.txt           1.2 KB   15:45
    ///  3)  image.png              500 KB   16:20
    ///
    /// === Add File to Stack ===
    /// Select file to add to stack
    /// Enter file number (or 'b' to back/cancel): 2
    ///
    /// ✓ Added 'document.txt' to file stack. Total files: 1
    /// ```
    ///
    /// # Error Handling
    /// - Validates numbered selections against navigation lookup table
    /// - Ensures selected items are files, not directories
    /// - Provides clear error messages for invalid selections
    /// - Handles cancellation gracefully
    /// - Manages IO errors during user interaction
    pub fn interactive_add_file_tostack(
        &mut self,
        nav_state: &NavigationState,
        current_directory_entries: &[FileSystemEntry],
        current_directory_path: &PathBuf,
    ) -> Result<()> {
        // WORKFLOW STEP 1: Display current directory contents
        // This shows the current page with existing filters and numbering
        display_directory_contents(
            current_directory_entries,
            current_directory_path,
            None, // Pagination info handled by main navigation
            nav_state.current_filter,
            nav_state,
        )
        .map_err(|e| FileFantasticError::Io(e))?;

        // WORKFLOW STEP 2: Prompt for file selection
        println!("\n=== Add File to Stack ===");
        println!("Select file to add to stack");
        print!("Enter file number (or 'b' to back/cancel): ");
        io::stdout()
            .flush()
            .map_err(|e| FileFantasticError::Io(e))?;

        // Read user input
        let mut input = String::new();
        io::stdin()
            .read_line(&mut input)
            .map_err(|e| FileFantasticError::Io(e))?;
        let input = input.trim();

        // Handle cancellation request
        if input.eq_ignore_ascii_case("b") {
            println!("Back/Cancelled.");
            return Ok(());
        }

        // WORKFLOW STEP 3: Validate and process the user's selection
        if let Ok(number) = input.parse::<usize>() {
            // Use navigation state's lookup to find the selected item
            if let Some(item_info) = nav_state.lookup_item(number) {
                // Check if selected item is a file (not a directory)
                if item_info.item_type == FileSystemItemType::Directory {
                    // User selected a directory - show error and return
                    let item_name = item_info
                        .item_path
                        .file_name()
                        .unwrap_or_default()
                        .to_string_lossy();
                    eprintln!(
                        "\n✗ Error: '{}' is a directory. Please select a file.",
                        item_name
                    );
                } else {
                    // WORKFLOW STEP 4: It's a file - add to stack

                    // Extract file name for display
                    let file_name = item_info
                        .item_path
                        .file_name()
                        .unwrap_or_default()
                        .to_string_lossy();

                    // Add the file to the stack
                    match self.add_file_to_stack(item_info.item_path.clone()) {
                        Ok(()) => {
                            // Success - show confirmation with stack count
                            println!(
                                "\n✓ Added '{}' to file stack. Total files: {}",
                                file_name,
                                self.file_path_stack.len()
                            );
                        }
                        Err(e) => {
                            // Failed to add to stack - show error
                            eprintln!("\n✗ Failed to add file to stack: {}", e);
                        }
                    }
                }
            } else {
                // Invalid item number - not in lookup table
                println!("Error: Invalid item number {}. Please try again.", number);
            }
        } else {
            // Input was not a valid number
            println!("Error: Please enter a valid number or 'b' to cancel.");
        }

        // Wait for user acknowledgment before returning to main interface
        println!("\nPress Enter to continue...");
        let _ = io::stdin().read_line(&mut String::new());

        Ok(())
    }


    // /// Helper function to select and retrieve a file from the file stack
    // ///
    // /// # Purpose
    // /// Internal helper that handles the file-specific retrieval logic.
    // /// This is essentially the existing `interactive_get_file_from_stack` function
    // /// but renamed to clarify its role as a helper in the new architecture.
    // ///
    // /// # Returns
    // /// * `Result<Option<PathBuf>>` - Selected file path, None if canceled, or error
    // ///
    // /// # Behavior
    // /// - Displays all files in the stack (most recent first)
    // /// - Allows selection by number or default to most recent
    // /// - Returns the file path without removing it from stack
    // /// - No destructive operations performed
    // ///
    // /// # Note
    // /// This function maintains the exact same behavior as the original
    // /// `interactive_get_file_from_stack` for consistency.
    // fn get_file_from_stack_helper(&mut self) -> Result<Option<PathBuf>> {
    //     // Check if stack is empty (redundant check for safety)
    //     if self.file_path_stack.is_empty() {
    //         println!("File stack is empty.");
    //         return Ok(None);
    //     }

    //     println!("\n=== File Stack ===");

    //     // Display files in reverse order (most recent first) for user-friendly numbering
    //     for (i, file) in self.file_path_stack.iter().enumerate().rev() {
    //         println!(
    //             "{}. {}",
    //             self.file_path_stack.len() - i,
    //             file.file_name().unwrap_or_default().to_string_lossy()
    //         );
    //     }

    //     print!("Select file number (Enter for most recent, 'c' to cancel): ");
    //     io::stdout()
    //         .flush()
    //         .map_err(|e| FileFantasticError::Io(e))?;

    //     let mut input = String::new();
    //     io::stdin()
    //         .read_line(&mut input)
    //         .map_err(|e| FileFantasticError::Io(e))?;
    //     let input = input.trim();

    //     // Handle cancellation
    //     if input.eq_ignore_ascii_case("c") {
    //         println!("Cancelled.");
    //         return Ok(None);
    //     }

    //     // Default to most recent if no input
    //     if input.is_empty() {
    //         if let Some(file) = self.file_path_stack.last() {
    //             println!(
    //                 "Retrieved: {}",
    //                 file.file_name().unwrap_or_default().to_string_lossy()
    //             );
    //             return Ok(Some(file.clone()));
    //         }
    //     }

    //     // Try to parse as index and validate
    //     if let Ok(index) = input.parse::<usize>() {
    //         if index > 0 && index <= self.file_path_stack.len() {
    //             // Convert to actual vector index (1-based display to 0-based storage)
    //             let actual_index = self.file_path_stack.len() - index;

    //             // Use .get() for bounds-checked access
    //             if let Some(file) = self.file_path_stack.get(actual_index) {
    //                 println!(
    //                     "Retrieved: {}",
    //                     file.file_name().unwrap_or_default().to_string_lossy()
    //                 );
    //                 return Ok(Some(file.clone()));
    //             } else {
    //                 println!("Error: Index out of bounds");
    //             }
    //         } else {
    //             println!(
    //                 "Error: Invalid file number {}. Valid range: 1-{}",
    //                 index,
    //                 self.file_path_stack.len()
    //             );
    //         }
    //     } else {
    //         println!(
    //             "Error: Please enter a valid number, press Enter for most recent, or 'c' to cancel."
    //         );
    //     }

    //     Ok(None)
    // }


    // /// Gets and removes the most recent file from the file stack
    // ///
    // /// # Purpose
    // /// Removes and returns the most recently added file from the file stack,
    // /// implementing LIFO (Last In, First Out) behavior.
    // ///
    // /// # Returns
    // /// * `Option<PathBuf>` - The most recent file path, or None if stack is empty
    // ///
    // /// # Stack Behavior
    // /// - Removes the last element added to the stack
    // /// - Returns None if the stack is empty
    // /// - Modifies the stack by removing the returned element
    // ///
    // /// # Usage Context
    // /// Used when performing operations on collected files:
    // /// - Processing files in reverse order of collection
    // /// - Undoing file additions
    // /// - Batch operations where order matters
    // ///
    // /// # Example
    // /// ```rust
    // /// match state_manager.pop_file_from_stack() {
    // ///     Some(file_path) => println!("Processing: {}", file_path.display()),
    // ///     None => println!("No files in stack"),
    // /// }
    // /// ```
    // pub fn pop_file_from_stack(&mut self) -> Option<PathBuf> {
    //     self.file_path_stack.pop()
    // }


    // /// Q&A interface to select and return file from stack
    // ///
    // /// # Purpose
    // /// Provides an interactive interface for selecting a file from the file stack,
    // /// displaying all available files and allowing selection by number.
    // /// This uses the same numbered selection paradigm as the rest of the application.
    // ///
    // /// # Returns
    // /// * `Result<Option<PathBuf>>` - Selected file path, None if canceled, or error
    // ///
    // /// # User Interface Flow
    // /// 1. Check if file stack is empty
    // /// 2. Display all files in the stack with numbers (most recent first)
    // /// 3. Allow user to select by number or default to most recent
    // /// 4. Remove and return the selected file
    // /// 5. Display confirmation of selection
    // ///
    // /// # Selection Options
    // /// - Enter number: Select specific file by index
    // /// - Enter (empty): Select most recent file (top of stack)
    // /// - 'c': Cancel operation
    // /// - Invalid number: Display error and return None
    // ///
    // /// # Display Format
    // /// Files are displayed in reverse order (most recent first) with 1-based indexing
    // /// to match user expectations and maintain consistency with main interface.
    // ///
    // /// # Example Interaction
    // /// ```text
    // /// === File Stack ===
    // /// 1. document.txt
    // /// 2. image.png
    // /// 3. script.sh
    // /// Select file number (Enter for most recent, 'c' to cancel): 2
    // /// Retrieved: image.png
    // /// ```
    // pub fn interactive_get_file_from_stack(&mut self) -> Result<Option<PathBuf>> {
    //     // Check if stack is empty
    //     if self.file_path_stack.is_empty() {
    //         println!("File stack is empty.");
    //         return Ok(None);
    //     }

    //     println!("\n=== File Stack ===");
    //     // Display files in reverse order (most recent first) for user-friendly numbering
    //     for (i, file) in self.file_path_stack.iter().enumerate().rev() {
    //         println!(
    //             "{}. {}",
    //             self.file_path_stack.len() - i,
    //             file.file_name().unwrap_or_default().to_string_lossy()
    //         );
    //     }

    //     print!("Select file number (Enter for most recent, 'c' to cancel): ");
    //     io::stdout()
    //         .flush()
    //         .map_err(|e| FileFantasticError::Io(e))?;

    //     let mut input = String::new();
    //     io::stdin()
    //         .read_line(&mut input)
    //         .map_err(|e| FileFantasticError::Io(e))?;
    //     let input = input.trim();

    //     // Handle cancellation
    //     if input.eq_ignore_ascii_case("c") {
    //         println!("Cancelled.");
    //         return Ok(None);
    //     }

    //     // Default to most recent (pop from end) if no input
    //     if input.is_empty() {
    //         if let Some(file) = self.pop_file_from_stack() {
    //             println!(
    //                 "Retrieved: {}",
    //                 file.file_name().unwrap_or_default().to_string_lossy()
    //             );
    //             return Ok(Some(file));
    //         }
    //     }

    //     // Try to parse as index and validate
    //     if let Ok(index) = input.parse::<usize>() {
    //         if index > 0 && index <= self.file_path_stack.len() {
    //             // Convert to actual vector index (1-based display to 0-based storage)
    //             let actual_index = self.file_path_stack.len() - index;

    //             // Use .get() for bounds-checked access
    //             if let Some(file) = self.file_path_stack.get(actual_index) {
    //                 println!(
    //                     "Retrieved: {}",
    //                     file.file_name().unwrap_or_default().to_string_lossy()
    //                 );
    //                 return Ok(Some(file.clone())); // Clone to return ownership
    //             } else {
    //                 println!("Error: Index out of bounds");
    //             }
    //         } else {
    //             println!(
    //                 "Error: Invalid file number {}. Valid range: 1-{}",
    //                 index,
    //                 self.file_path_stack.len()
    //             );
    //         }
    //     } else {
    //         println!(
    //             "Error: Please enter a valid number, press Enter for most recent, or 'c' to cancel."
    //         );
    //     }

    //     Ok(None)
    // }
                            GetSendModeAction::GetFileFromStack => {
                                        match state_manager.interactive_get_item_from_stack() {
                                            Ok(Some(source_file_path)) => {
                                                println!(
                                                    "Retrieved file: {}",
                                                    source_file_path.display()
                                                );
                                                println!(
                                                    "Copying to current directory: {}",
                                                    current_directory_path.display()
                                                );

                                                // Copy the file to current directory with archive handling
                                                match copy_file_with_archive_handling(
                                                    &source_file_path,
                                                    &current_directory_path,
                                                ) {
                                                    Ok(final_destination_path) => {
                                                        println!(
                                                            "✓ Copy operation completed successfully!"
                                                        );
                                                        println!(
                                                            "Final location: {}",
                                                            final_destination_path.display()
                                                        );
                                                    }
                                                    Err(e) => {
                                                        eprintln!("✗ Copy operation failed: {}", e);
                                                    }
                                                }

                                                println!("Press Enter to continue...");
                                                let _ = io::stdin().read_line(&mut String::new());
                                            }
                                            Ok(None) => println!("No file selected."),
                                            Err(e) => {
                                                println!("Error getting file from stack: {}", e)
                                            }
                                        }
                                    }
                                    /*
                                    pending future functions to used saved dir-stack items
                                    */
                                    // GetSendModeAction::AddDirectoryToStack => {
                                    //     match state_manager.interactive_save_directory_to_stack(&current_directory_path) {
                                    //         Ok(_) => println!("Directory added to stack successfully."),
                                    //         Err(e) => println!("Error adding directory to stack: {}", e),
                                    //     }
                                    // },


/ /// Vanilla home made pair compair levenshtein_distance
// /// e.g. for simple fuzzy search
// /// Calculates the Levenshtein distance between two strings
// ///
// /// # Purpose
// /// Provides fuzzy text matching capability for the search functionality,
// /// measuring how many single-character edits (insertions, deletions, substitutions)
// /// are needed to transform one string into another.
// ///
// /// # Arguments
// /// * `s` - First string for comparison
// /// * `t` - Second string for comparison
// ///
// /// # Returns
// /// * `usize` - The edit distance between the strings (lower = more similar)
// ///
// /// # Algorithm
// /// Uses a dynamic programming approach with two work vectors to calculate
// /// the minimum edit distance between strings:
// /// - 0 means strings are identical
// /// - Higher values indicate greater differences
// /// - Equal to max(s.len(), t.len()) when strings share no characters
// ///
// /// # Performance Considerations
// /// - O(m*n) time complexity where m and n are string lengths
// /// - O(n) space complexity using the two-vector approach
// /// - Efficient for short strings like filenames, but may not scale well
// ///   for very long strings
// ///
// /// # Usage Context
// /// Used in the `fuzzy_search` method to find files matching a partial query,
// /// allowing for approximate/inexact matches when users don't know the exact filename.
// ///
// /// # Examples
// /// ```
// /// assert_eq!(levenshtein_distance("kitten", "sitting"), 3);
// /// assert_eq!(levenshtein_distance("rust", "dust"), 1);
// /// assert_eq!(levenshtein_distance("", "test"), 4);
// /// ```
// fn levenshtein_distance(s: &str, t: &str) -> usize {
//     // Convert strings to vectors of chars for easier indexing
//     // Do this FIRST to get correct character counts
//     let s_chars: Vec<char> = s.chars().collect();
//     let t_chars: Vec<char> = t.chars().collect();

//     // Get the CHARACTER lengths, not byte lengths
//     let m = s_chars.len();
//     let n = t_chars.len();

//     // Handle empty string cases
//     if m == 0 {
//         return n;
//     }
//     if n == 0 {
//         return m;
//     }

//     // Create two work vectors
//     let mut v0: Vec<usize> = (0..=n).collect();
//     let mut v1: Vec<usize> = vec![0; n + 1];

//     // Iterate through each character of s
//     for i in 0..m {
//         // First element of v1 is the deletion cost
//         v1[0] = i + 1;

//         // Calculate costs for each character of t
//         for j in 0..n {
//             let deletion_cost = v0[j + 1] + 1;
//             let insertion_cost = v1[j] + 1;
//             let substitution_cost = v0[j] + if s_chars[i] == t_chars[j] { 0 } else { 1 };

//             v1[j + 1] = deletion_cost.min(insertion_cost).min(substitution_cost);
//         }

//         // Swap vectors for next iteration
//         std::mem::swap(&mut v0, &mut v1);
//     }

//     // Return final distance
//     v0[n]
// }


    /*
    pending use of saved directories
    */
    // /// Q&A interface to save current directory to directory stack
    // ///
    // /// # Purpose
    // /// Provides an interactive interface for adding the current directory
    // /// to the directory stack, with user confirmation.
    // ///
    // /// # Arguments
    // /// * `current_directory` - The current directory to potentially add
    // ///
    // /// # Returns
    // /// * `Result<()>` - Success or error with context
    // ///
    // /// # User Interface Flow
    // /// 1. Display the current directory path
    // /// 2. Ask for user confirmation to add it to the stack
    // /// 3. Add to stack if user confirms (default is yes)
    // /// 4. Display confirmation with current stack size
    // ///
    // /// # Confirmation Logic
    // /// - Empty input or 'y'/'Y': Add to stack
    // /// - Any other input: Do not add to stack
    // ///
    // /// # Example Interaction
    // /// ```text
    // /// === Add Directory to Stack ===
    // /// Current directory: /home/user/projects
    // /// Add current directory to stack? (Y/n):
    // /// Added to directory stack. Total directories: 2
    // /// ```
    // pub fn interactive_save_directory_to_stack(&mut self, current_directory: &PathBuf) -> Result<()> {
    //     println!("\n=== Add Directory to Stack ===");
    //     println!("Current directory: {}", current_directory.display());

    //     print!("Add current directory to stack? (Y/n): ");
    //     io::stdout().flush().map_err(|e| FileFantasticError::Io(e))?;

    //     let mut response = String::new();
    //     io::stdin().read_line(&mut response).map_err(|e| FileFantasticError::Io(e))?;

    //     // Default to 'yes' if user just presses enter
    //     if response.trim().is_empty() || response.trim().eq_ignore_ascii_case("y") {
    //         self.add_directory_to_stack(current_directory.clone())?;
    //         println!("Added to directory stack. Total directories: {}", self.directory_path_stack.len());
    //     } else {
    //         println!("Cancelled.");
    //     }

    //     Ok(())
    // }

    // /// Interactive interface to save a specific directory to the directory stack
    // ///
    // /// # Purpose
    // /// Provides an interactive confirmation interface for adding a specific directory
    // /// to the directory stack. Typically used for adding the current working directory
    // /// without needing to select from a list.
    // ///
    // /// # Arguments
    // /// * `directory_path` - The directory path to potentially add (not necessarily current)
    // ///
    // /// # Returns
    // /// * `Result<()>` - Success or error with context
    // ///
    // /// # User Interface Flow
    // /// 1. Display the directory path to be added
    // /// 2. Ask for user confirmation
    // /// 3. Add to stack if user confirms (default is yes)
    // /// 4. Display confirmation with stack size
    // ///
    // /// # Note on Parameter Name Change
    // /// Changed from `current_directory` to `directory_path` to better reflect that
    // /// this can be ANY directory path, not just the current one.
    // ///
    // /// # Example Usage
    // /// ```rust
    // /// // Add current working directory
    // /// state_manager.interactive_save_directory_to_stack(&current_dir)?;
    // ///
    // /// // Add a specific directory
    // /// let project_dir = PathBuf::from("/home/user/projects");
    // /// state_manager.interactive_save_directory_to_stack(&project_dir)?;
    // /// ```
    // pub fn interactive_save_directory_to_stack(&mut self, directory_path: &PathBuf) -> Result<()> {
    //     println!("\n=== Add Directory to Stack ===");
    //     println!("Directory: {}", directory_path.display());

    //     print!("Add this directory to stack? (Y/n): ");
    //     io::stdout()
    //         .flush()
    //         .map_err(|e| FileFantasticError::Io(e))?;

    //     let mut response = String::new();
    //     io::stdin()
    //         .read_line(&mut response)
    //         .map_err(|e| FileFantasticError::Io(e))?;

    //     // Default to 'yes' if user just presses enter or explicitly says yes
    //     if response.trim().is_empty() || response.trim().eq_ignore_ascii_case("y") {
    //         match self.add_directory_to_stack(directory_path.clone()) {
    //             Ok(()) => {
    //                 println!(
    //                     "✓ Added to directory stack. Total directories: {}",
    //                     self.directory_path_stack.len()
    //                 );
    //             }
    //             Err(e) => {
    //                 eprintln!("✗ Failed to add directory to stack: {}", e);
    //             }
    //         }
    //     } else {
    //         println!("Cancelled.");
    //     }

    //     Ok(())
    // }


    // /// Interactive interface to add a file to the file stack
    // ///
    // /// # Purpose
    // /// Provides a simple interactive interface for adding files to the file stack.
    // /// Shows the current directory listing and prompts user to select a file by number.
    // /// Works with the current page view only, utilizing existing navigation state.
    // ///
    // /// # Arguments
    // /// * `nav_state` - Current navigation state with lookup table for numbered selection
    // /// * `current_directory_entries` - Current directory entries to display for selection (current page only)
    // /// * `current_directory_path` - Current directory path for display context
    // ///
    // /// # Returns
    // /// * `Result<()>` - Success or error with context
    // ///
    // /// # User Interface Workflow
    // ///
    // /// ## Step 1: Display Current View
    // /// - Show current directory contents with numbered items (same as main navigation)
    // /// - This respects current filter and pagination state
    // ///
    // /// ## Step 2: Selection Prompt
    // /// - User selects item by number (same interface as navigation)
    // /// - Can cancel with 'b' for back
    // ///
    // /// ## Step 3: Validation
    // /// - Verify selected item exists in lookup table
    // /// - Ensure selected item is a file (not a directory)
    // ///
    // /// ## Step 4: Add to Stack
    // /// - Add file path to the file stack
    // /// - Display confirmation with updated stack count
    // ///
    // /// # Example Interaction
    // /// ```text
    // /// Current Directory: /home/user/documents
    // ///
    // /// Num  Name                    Size     Modified
    // /// ------------------------------------------------
    // ///  1)  folder1/               -        14:30
    // ///  2)  document.txt           1.2 KB   15:45
    // ///  3)  image.png              500 KB   16:20
    // ///
    // /// === Add File to Stack ===
    // /// Select file to add to stack
    // /// Enter file number (or 'b' to back/cancel): 2
    // ///
    // /// ✓ Added 'document.txt' to file stack. Total files: 1
    // /// ```
    // ///
    // /// # Error Handling
    // /// - Validates numbered selections against navigation lookup table
    // /// - Ensures selected items are files, not directories
    // /// - Provides clear error messages for invalid selections
    // /// - Handles cancellation gracefully
    // /// - Manages IO errors during user interaction
    // pub fn interactive_add_file_tostack(
    //     &mut self,
    //     nav_state: &NavigationState,
    //     current_directory_entries: &[FileSystemEntry],
    //     current_directory_path: &PathBuf,
    // ) -> Result<()> {
    //     // WORKFLOW STEP 1: Display current directory contents
    //     // This shows the current page with existing filters and numbering
    //     display_directory_contents(
    //         current_directory_entries,
    //         current_directory_path,
    //         None, // Pagination info handled by main navigation
    //         nav_state.current_filter,
    //         nav_state,
    //     )
    //     .map_err(|e| FileFantasticError::Io(e))?;

    //     // WORKFLOW STEP 2: Prompt for file selection
    //     println!("\n=== Add File to Stack ===");
    //     println!("Select file to add to stack");
    //     print!("Enter file number (or 'b' to back/cancel): ");
    //     io::stdout()
    //         .flush()
    //         .map_err(|e| FileFantasticError::Io(e))?;

    //     // Read user input
    //     let mut input = String::new();
    //     io::stdin()
    //         .read_line(&mut input)
    //         .map_err(|e| FileFantasticError::Io(e))?;
    //     let input = input.trim();

    //     // Handle cancellation request
    //     if input.eq_ignore_ascii_case("b") {
    //         println!("Back/Cancelled.");
    //         return Ok(());
    //     }

    //     // WORKFLOW STEP 3: Validate and process the user's selection
    //     if let Ok(number) = input.parse::<usize>() {
    //         // Use navigation state's lookup to find the selected item
    //         if let Some(item_info) = nav_state.lookup_item(number) {
    //             // Check if selected item is a file (not a directory)
    //             if item_info.item_type == FileSystemItemType::Directory {
    //                 // User selected a directory - show error and return
    //                 let item_name = item_info
    //                     .item_path
    //                     .file_name()
    //                     .unwrap_or_default()
    //                     .to_string_lossy();
    //                 eprintln!(
    //                     "\n✗ Error: '{}' is a directory. Please select a file.",
    //                     item_name
    //                 );
    //             } else {
    //                 // WORKFLOW STEP 4: It's a file - add to stack

    //                 // Extract file name for display
    //                 let file_name = item_info
    //                     .item_path
    //                     .file_name()
    //                     .unwrap_or_default()
    //                     .to_string_lossy();

    //                 // Add the file to the stack
    //                 match self.add_file_to_stack(item_info.item_path.clone()) {
    //                     Ok(()) => {
    //                         // Success - show confirmation with stack count
    //                         println!(
    //                             "\n✓ Added '{}' to file stack. Total files: {}",
    //                             file_name,
    //                             self.file_path_stack.len()
    //                         );
    //                     }
    //                     Err(e) => {
    //                         // Failed to add to stack - show error
    //                         eprintln!("\n✗ Failed to add file to stack: {}", e);
    //                     }
    //                 }
    //             }
    //         } else {
    //             // Invalid item number - not in lookup table
    //             println!("Error: Invalid item number {}. Please try again.", number);
    //         }
    //     } else {
    //         // Input was not a valid number
    //         println!("Error: Please enter a valid number or 'b' to cancel.");
    //     }

    //     // Wait for user acknowledgment before returning to main interface
    //     println!("\nPress Enter to continue...");
    //     let _ = io::stdin().read_line(&mut String::new());

    //     Ok(())
    // }


// /// Formats a timestamp into a human-readable format
// ///
// /// # Purpose
// /// Converts system timestamps into user-friendly date/time representations
// /// that adapt based on how recent the timestamp is, prioritizing relevant
// /// information over complete timestamps.
// ///
// /// # Arguments
// /// * `timestamp` - SystemTime to format
// ///
// /// # Returns
// /// * String - Formatted date/time string
// ///
// /// # Format Rules
// /// The function uses different formats based on the age of the timestamp:
// /// - Today: "HH:MM" (e.g., "14:30")
// /// - This year: "MM-DD HH:MM" (e.g., "09-15 14:30")
// /// - Older: "YYYY-MM-DD" (e.g., "2022-09-15")
// ///
// /// # Timezone Behavior
// /// All times are displayed in the local system timezone.
// ///
// /// # Edge Cases
// /// - For timestamps that can't be compared with now (future with TryFrom error),
// ///   falls back to displaying them as if they're old timestamps
// /// - The Unix epoch (1970-01-01) is handled correctly and displayed as "1970-01-01"
// ///
// /// # Examples
// /// ```rust
// /// // Format the current time (will show HH:MM)
// /// let now = SystemTime::now();
// /// let formatted = format_timestamp(now);
// ///
// /// // Format a file's modification time
// /// let metadata = fs::metadata("example.txt")?;
// /// let modified = metadata.modified()?;
// /// let formatted = format_timestamp(modified);
// /// ```
// fn format_timestamp(timestamp: SystemTime) -> String {
//     // Get current time and the file time as Duration since UNIX_EPOCH
//     let now = SystemTime::now();

//     // Convert timestamps to Duration since UNIX_EPOCH, handling errors
//     let now_duration = now
//         .duration_since(UNIX_EPOCH)
//         .unwrap_or(Duration::from_secs(0));
//     let file_duration = timestamp
//         .duration_since(UNIX_EPOCH)
//         .unwrap_or(Duration::from_secs(0));

//     // Convert to seconds
//     let now_secs = now_duration.as_secs();
//     let file_secs = file_duration.as_secs();

//     // Calculate time components
//     let secs_per_day = 24 * 60 * 60;
//     let days_diff = (now_secs - file_secs) / secs_per_day;

//     // Get components for the file timestamp
//     let (year, month, day, hour, minute) = seconds_to_components(file_secs);
//     let (current_year, _, _) = seconds_to_ymd(now_secs);

//     // Format based on how old the file is
//     if days_diff == 0 {
//         // Today: show time only
//         format!("{:02}:{:02}", hour, minute)
//     } else if year == current_year {
//         // This year: show month-day and time
//         format!("{:02}-{:02} {:02}:{:02}", month, day, hour, minute)
//     } else {
//         // Older: show full date
//         format!("{}-{:02}-{:02}", year, month, day)
//     }
// }


// lacks enforcement of minimum
/// Calculates the actual name column width based on user adjustments
///
/// # Purpose
/// Determines how many characters wide the name column should be by applying
/// the user's adjustment to the default baseline. This width controls how much
/// of each filename is visible before truncation.
///
/// # Arguments
/// * `adjustment_magnitude` - The positive number of characters to add or remove
/// * `adjustment_direction_true_is_positive_false_is_negative` - Direction of adjustment:
///   - `true` = Add characters (wider column)
///   - `false` = Remove characters (narrower column)
///
/// # Returns
/// * `u16` - The calculated column width in characters
///
/// # Calculation Logic
/// 1. Start with MAX_NAME_LENGTH_DEFAULT (55 characters)
/// 2. Apply adjustment in the specified direction
/// 3. Use saturating arithmetic to prevent overflow
/// 4. Enforce minimum width of 8 characters (FILENAME_SUFFIX_LENGTH + 3 for "...")
///
/// # Minimum Width Rationale
/// The minimum of 8 characters ensures we can always display:
/// - 3 characters for ellipsis "..."
/// - 5 characters for file suffix (e.g., ".docx")
/// This prevents display corruption with very narrow columns.
///
/// # Examples
/// ```rust
/// // Default width (no adjustment)
/// assert_eq!(calculate_name_width(0, true), 55);
///
/// // Increase width by 10
/// assert_eq!(calculate_name_width(10, true), 65);
///
/// // Decrease width by 50 (hits minimum)
/// assert_eq!(calculate_name_width(50, false), 8);
///
/// // Maximum possible width
/// assert_eq!(calculate_name_width(u16::MAX, true), u16::MAX);
/// ```
fn calculate_name_width(
    adjustment_magnitude: u16,
    adjustment_direction_true_is_positive_false_is_negative: bool,
) -> u16 {
    // Convert default to u16 for calculation
    let base_width: u16 = MAX_NAME_LENGTH_DEFAULT as u16;

    // Calculate minimum allowed width (suffix + ellipsis)
    let minimum_width: u16 = (FILENAME_SUFFIX_LENGTH + 3) as u16;

    // Apply adjustment based on direction
    if adjustment_direction_true_is_positive_false_is_negative {
        // Positive adjustment: add to base width
        // saturating_add prevents overflow, returns u16::MAX if result would overflow
        base_width.saturating_add(adjustment_magnitude)
    } else {
        // Negative adjustment: subtract from base width
        // saturating_sub prevents underflow, returns 0 if result would be negative
        // max ensures we never go below minimum_width
        base_width
            .saturating_sub(adjustment_magnitude)
            .max(minimum_width)
    }
}


main with source-it otherwise// src/main.rs

// import file fantstic module w/ these 2 lines
mod ff_file_fantastic_module;
use ff_file_fantastic_module::file_fantastic;

// import rows and columns helper module w/ these 3 lines
mod csv_processor_module;
mod error_types_module;
mod rows_and_columns_module;

// Share Source
mod source_it_module;
// use source_it_module::{SourcedFile, handle_sourceit_command};

// // Developer explicitly lists files to embed
// const FF_SOURCE_FILES: &[SourcedFile] = &[
//     SourcedFile::new("Cargo.toml", include_str!("../Cargo.toml")),
//     SourcedFile::new("src/main.rs", include_str!("main.rs")),
//     SourcedFile::new(
//         "src/csv_processor_module.rs",
//         include_str!("csv_processor_module.rs"),
//     ),
//     SourcedFile::new(
//         "src/error_types_module.rs",
//         include_str!("error_types_module.rs"),
//     ),
//     SourcedFile::new(
//         "src/ff_file_fantastic_module.rs",
//         include_str!("ff_file_fantastic_module.rs"),
//     ),
//     SourcedFile::new(
//         "src/rows_and_columns_module.rs",
//         include_str!("rows_and_columns_module.rs"),
//     ),
//     SourcedFile::new(
//         "src/source_it_module.rs",
//         include_str!("source_it_module.rs"),
//     ),
//     SourcedFile::new("README.md", include_str!("../README.md")),
//     SourcedFile::new("LICENSE", include_str!("../LICENSE")),
//     SourcedFile::new(
//         "testtesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttest.txt",
//         include_str!(
//             "../testtesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttesttest.txt"
//         ),
//     ),
//     SourcedFile::new("test.csv", include_str!("../test.csv")),
//     SourcedFile::new(".gitignore", include_str!("../.gitignore")),
// ];

fn main() {
    // let args: Vec<String> = std::env::args().collect();

    // if args.contains(&"--source".to_string()) {
    //     match handle_sourceit_command("ff_file_fantastic", None, FF_SOURCE_FILES) {
    //         Ok(path) => println!("Source extracted to: {}", path.display()),
    //         Err(e) => eprintln!("Failed to extract source: {}", e),
    //     }
    //     return;
    // }

    // Let's call File Fantastic Go!!
    if let Err(e) = file_fantastic() {
        // Handle errors
        eprintln!("Error: {}", e);

        // exit code one means ok!
        std::process::exit(1);
    }
}



/// Constructs and returns a formatted version statement for the application.
///
/// # Returns
///
/// A `String` containing package name and version
///
/// # Example
///
/// ```
/// let version_info = get_version_statement();
/// println!("{}", version_info);
/// // Output: my-app 1.0.0
/// ```
pub fn get_version_statement() -> String {
    format!("{} {}", PKG_NAME, VERSION)
}

/// Writes version information to stdout.
///
/// # Returns
///
/// * `Ok(())` if version information was successfully written
/// * `Err(FileFantasticError)` if writing or flushing failed
///
/// # Errors
///
/// Returns an error if stdout is not available or writing fails
/// (e.g., broken pipe, redirected to read-only location)
pub fn display_version() -> Result<()> {
    let mut stdout = io::stdout();

    // Write version statement
    writeln!(stdout, "{}", get_version_statement()).map_err(|e| FileFantasticError::Io(e))?;

    // Ensure output is flushed
    stdout.flush().map_err(|e| FileFantasticError::Io(e))?;

    Ok(())
}

/// Checks if version information was requested via command line arguments.
///
/// # Arguments
///
/// * `args` - A slice of string references representing command line arguments
///
/// # Returns
///
/// `true` if either "--version" or "-v" is found in the arguments
pub fn is_version_requested(args: &[String]) -> bool {
    args.iter().any(|arg| arg == "--version" || arg == "-v")
}

/// Version information embedded at compile time from Cargo.toml
///
/// These constants are populated by the Rust compiler using the env! macro,
/// which reads environment variables that Cargo sets during compilation.
const VERSION: &str = env!("CARGO_PKG_VERSION");
const PKG_NAME: &str = env!("CARGO_PKG_NAME");


/// Gets the Rust compiler version by executing rustc --version
///
/// # Returns
/// String containing the rustc version (e.g., "1.75.0")
fn get_rustc_version() -> String {
    match Command::new("rustc").arg("--version").output() {
        Ok(output) => {
            if output.status.success() {
                let version_string = String::from_utf8_lossy(&output.stdout);
                // Parse "rustc 1.75.0 (abcdef 2024-01-15)" to get just "1.75.0"
                version_string
                    .split_whitespace()
                    .nth(1)
                    .unwrap_or("unknown")
                    .to_string()
            } else {
                String::from("unknown")
            }
        }
        Err(_) => String::from("unknown"),
    }
}



// /// Writes version information to stdout.
// ///
// /// # Returns
// ///
// /// * `Ok(())` if version information was successfully written
// /// * `Err(FileFantasticError)` if writing or flushing failed
// ///
// /// # Errors
// ///
// /// Returns an error if stdout is not available or writing fails
// /// (e.g., broken pipe, redirected to read-only location)
// pub fn display_version() -> Result<()> {
//     let mut stdout = io::stdout();

//     // Write version statement
//     writeln!(stdout, "{}", format_version_info()).map_err(|e| FileFantasticError::Io(e))?;

//     // Ensure output is flushed
//     stdout.flush().map_err(|e| FileFantasticError::Io(e))?;

//     Ok(())
// }

// use std::io::{self, Write};



// /// Compile-time version information from Cargo.toml
// const VERSION: &str = env!("CARGO_PKG_VERSION");
// const PKG_NAME: &str = env!("CARGO_PKG_NAME");



/// Constructs and returns a formatted version statement from compile-time constants.
///
/// This function uses compile-time constants that should always be available,
/// but returns a Result for consistency and future-proofing.
///
/// # Returns
///
/// * `Ok(String)` containing package name and version
/// * `Err` if the constants are somehow invalid (extremely unlikely)
///
/// # Example
///
/// ```
/// match backup_get_version_statement() {
///     Ok(version) => println!("{}", version),
///     Err(e) => eprintln!("Error: {}", e),
/// }
/// // Output: my-app 1.0.0
/// ```
pub fn backup_get_version_statement() -> Result<String> {
    // Validate that constants are not empty (defensive programming)
    if PKG_NAME.is_empty() || VERSION.is_empty() {
        return Err("Package name or version is empty".into());
    }

    Ok(format!("{} {}", PKG_NAME, VERSION))
}

/// Writes version information to stdout with three levels of failsafe.
///
/// Attempts to display version information in order of preference:
/// 1. Full version info from `format_version_info()`
/// 2. Basic version from compile-time constants
/// 3. Fallback constant string
///
/// # Returns
///
/// * `Ok(())` if any version information was successfully written
/// * `Err(FileFantasticError)` only if all attempts to write failed
///
/// # Errors
///
/// Returns an error only if stdout is completely unavailable and
/// all three levels of version output failed.
pub fn display_version() -> Result<()> {
    let mut stdout = io::stdout();

    // Level 1: Try full version info
    let full_version = format_version_info();

    // Check if full version is valid (not empty, not error-like)
    if !full_version.is_empty()
        && !full_version.contains("unknown")
        && !full_version.contains("not detected")
    {
        // Try to write full version
        if writeln!(stdout, "{}", full_version).is_ok() {
            // Successfully wrote, now flush and return
            return stdout.flush().map_err(|e| FileFantasticError::Io(e));
        }
        // Write failed, print warning and continue to fallback
        eprintln!("Warning: Failed to write full version info to stdout");
    }

    // Level 2: Try backup version from compile-time constants
    match backup_get_version_statement() {
        Ok(backup_version) => {
            if writeln!(stdout, "{}", backup_version).is_ok() {
                // Successfully wrote backup version
                return stdout.flush().map_err(|e| FileFantasticError::Io(e));
            }
            // Write failed, print warning and continue to final fallback
            eprintln!("Warning: Failed to write backup version info to stdout");
        }
        Err(e) => {
            // Even backup version construction failed (very unlikely)
            eprintln!("Warning: Could not construct backup version: {}", e);
        }
    }

    // Level 3: Last resort - try to write fallback constant
    if writeln!(stdout, "{}", FALLBACK_VERSION).is_ok() {
        // Even the minimal version worked
        return stdout.flush().map_err(|e| FileFantasticError::Io(e));
    }

    // All three attempts failed - stdout is completely broken
    eprintln!("Error: Could not write any version information to stdout");
    Err(FileFantasticError::Io(io::Error::new(
        io::ErrorKind::Other,
        "Failed to write any version information to stdout",
    )))
}



/// Scans directory and returns list of supported code/data files with line counts
///
/// # Arguments
/// * `directory_path` - Absolute path to directory to scan
///
/// # Returns
/// * `Vec<FileLineCount>` - List of files with their line counts
///
/// # Note
/// Skips files that cannot be processed (permissions, corruption, etc.)
/// and continues processing remaining files
fn get_code_files_with_counts(directory_path: &Path) -> Vec<FileLineCount> {
    let mut file_counts = Vec::new();

    // Read directory contents with error handling
    let entries = match fs::read_dir(directory_path) {
        Ok(entries) => entries,
        Err(e) => {
            eprintln!(
                "Error reading directory {}: {}",
                directory_path.display(),
                e
            );
            return file_counts;
        }
    };

    // Process each entry in the directory
    for entry_result in entries {
        let entry = match entry_result {
            Ok(entry) => entry,
            Err(e) => {
                eprintln!("Error reading directory entry: {}", e);
                continue; // Skip problematic entries
            }
        };

        let file_path = entry.path();

        // Skip directories, only process files
        if !file_path.is_file() {
            continue;
        }

        // Check if file has supported extension
        if !is_supported_file_type(&file_path) {
            continue;
        }

        // Get absolute path
        let absolute_path = match file_path.canonicalize() {
            Ok(path) => path,
            Err(e) => {
                eprintln!(
                    "Cannot get absolute path for {}: {}",
                    file_path.display(),
                    e
                );
                continue; // Skip files we can't resolve
            }
        };

        // Extract display name (filename only)
        let display_name = match absolute_path.file_name() {
            Some(name) => name.to_string_lossy().to_string(),
            None => {
                eprintln!("Cannot extract filename from {}", absolute_path.display());
                continue;
            }
        };

        // Count lines in file
        match count_file_lines_efficiently(&absolute_path) {
            Ok(line_count) => {
                file_counts.push(FileLineCount {
                    file_path: absolute_path,
                    display_name,
                    line_count,
                });
            }
            Err(e) => {
                eprintln!("Skipping file due to error: {}", e);
                continue; // Skip files we can't count
            }
        }
    }

    file_counts
}


/// Supported file extensions for code and data files
const SUPPORTED_EXTENSIONS: &[&str] = &[
    "csv", "tsv", "py", "rs", "js", "ts", "json", "xml", "yaml", "yml", "toml", "md", "txt", "sql",
    "sh", "bash", "c", "cpp", "h", "hpp", "java", "go", "rb", "php", "html", "css", "r", "scala",
    "kt",
];



/// Checks if a file has a supported code/data extension
///
/// # Arguments
/// * `file_path` - Path to the file to check
///
/// # Returns
/// * `true` if the file has a supported extension
/// * `false` otherwise
///
/// # Examples
/// ```
/// use std::path::Path;
/// assert!(is_supported_file_type(Path::new("test.rs")));
/// assert!(!is_supported_file_type(Path::new("test.exe")));
/// ```
fn is_supported_file_type(file_path: &Path) -> bool {
    // Get file extension as lowercase string
    let extension = match file_path.extension() {
        Some(ext) => ext.to_string_lossy().to_lowercase(),
        None => return false,
    };

    // Create HashSet for O(1) lookup performance
    let supported_set: HashSet<&str> = SUPPORTED_EXTENSIONS.iter().copied().collect();
    supported_set.contains(extension.as_str())
}


[profile.release]
# Maximum Link Time Optimization for best performance
lto = "fat"
# Single codegen unit maximizes optimization opportunities
codegen-units = 1
# Keep debug symbols for profiling capabilities
strip = "none"
# Use unwinding for better error handling without sacrificing much performance
panic = "unwind"
# Disable incremental compilation for maximum optimization
incremental = false
# Maximum optimization for speed
opt-level = 3
# Include minimal debug info for better profiling without much size impact
debug = 1
# Enable more aggressive optimizations
overflow-checks = false


    // // Directory/file mode on path-display line
    // let path_display = format!("{}", current_directory_path.display());
    // println!("{}\n{}{}", legend, filter_status, path_display);



/// Counts all items in a directory (flat, non-recursive, including hidden)
///
/// # Purpose
/// Provides summary statistics for directory contents to help users understand
/// the total scope of a directory when only a subset is displayed on screen.
///
/// # Arguments
/// * `path` - Reference to PathBuf of the directory to count
///
/// # Returns
/// A tuple of three Strings: (all_count, file_count, dir_count)
/// - `all_count`: Total number of items (files + dirs + symlinks + special files)
/// - `file_count`: Number of regular files only
/// - `dir_count`: Number of directories only
///
/// # Error Handling
/// Returns ("?", "?", "?") if any error occurs:
/// - Directory cannot be read (permissions, doesn't exist, etc.)
/// - Metadata cannot be accessed for items
/// - Directory has unreasonably large number of items (safety limit)
/// - Any other I/O error
///
/// This fail-safe approach ensures the TUI continues to function even if
/// counting fails, displaying "?" to indicate unknown counts.
///
/// # Scope
/// - Counts ONLY items in the specified directory (flat, non-recursive)
/// - Includes hidden files and directories (those starting with '.')
/// - Includes ALL item types (files, dirs, symlinks, FIFOs, sockets, etc.)
/// - Does NOT follow symlinks or recurse into subdirectories
///
/// # Item Classification
/// - Files: Regular files only
/// - Directories: Directories only
/// - All: Everything else goes into 'all' count only (symlinks, FIFOs, etc.)
///
/// # Safety
/// Uses a safety limit (1 million items) to prevent issues with corrupted
/// filesystems or unexpected conditions. If exceeded, returns "?" to indicate
/// an error condition rather than potentially incorrect counts.
///
/// # Examples
/// ```rust
/// let path = PathBuf::from("/home/user/documents");
/// let (all, files, dirs) = count_directory_items(&path);
/// println!("Total: {}, Files: {}, Directories: {}", all, files, dirs);
/// // Output: "Total: 42, Files: 35, Directories: 7"
///
/// // On error:
/// let bad_path = PathBuf::from("/nonexistent");
/// let (all, files, dirs) = count_directory_items(&bad_path);
/// // Returns: ("?", "?", "?")
/// ```
fn count_directory_items(path: &PathBuf) -> (String, String, String) {
    // Assertion: Path should not be empty (defensive check)
    assert!(!path.as_os_str().is_empty(), "Path should not be empty");

    // Initialize counters
    let mut all_count: u128 = 0;
    let mut file_count: u128 = 0;
    let mut dir_count: u128 = 0;

    // Safety limit: size of data type
    const MAX_DIRECTORY_ITEMS: u128 = u128::MAX;

    // Attempt to read directory contents
    let directory_reader = match fs::read_dir(path) {
        Ok(reader) => reader,
        Err(_) => {
            // Cannot read directory - return unknowns
            // Common causes: permission denied, path doesn't exist, not a directory
            return (String::from("?"), String::from("?"), String::from("?"));
        }
    };

    // Iterate through directory entries
    // Note: NOT using .take() - we count all items up to the safety limit
    for entry_result in directory_reader {
        // Safety check: prevent counting beyond reasonable limit
        // If we hit this, something is wrong (corrupted filesystem, bug, etc.)
        if all_count >= MAX_DIRECTORY_ITEMS {
            // Directory is unreasonably large - return error indicators
            // This is a safety mechanism, not a normal operating condition
            return (String::from("?"), String::from("?"), String::from("?"));
        }

        // Check each entry
        let entry = match entry_result {
            Ok(e) => e,
            Err(_) => {
                // Error reading this specific entry - skip it
                // This can happen with corrupted entries or permission issues
                continue;
            }
        };

        // Get metadata for the entry
        let metadata = match entry.metadata() {
            Ok(meta) => meta,
            Err(_) => {
                // Cannot read metadata for this entry - skip it
                // Can occur with broken symlinks or permission issues
                continue;
            }
        };

        // Count this item in 'all'
        all_count += 1;

        // Classify the item type
        if metadata.is_file() {
            // Regular file
            file_count += 1;
        } else if metadata.is_dir() {
            // Directory
            dir_count += 1;
        }
        // Note: Symlinks, FIFOs, sockets, etc. are counted only in 'all'
        // They increment all_count but not file_count or dir_count
    }

    // Assertion: Sanity check on counts (defensive programming)
    assert!(
        file_count + dir_count <= all_count,
        "Files + Directories should not exceed total count"
    );

    // Convert counts to strings
    let all_str = all_count.to_string();
    let file_str = file_count.to_string();
    let dir_str = dir_count.to_string();

    (all_str, file_str, dir_str)
}


// works perfectly well, replaced with 'ribbon' external array variable
// /// Counts all items in a directory (flat, non-recursive, including hidden)
// ///
// /// # Purpose
// /// Provides summary statistics for directory contents to help users understand
// /// the total scope of a directory when only a subset is displayed on screen.
// ///
// /// # Arguments
// /// * `path` - Reference to PathBuf of the directory to count
// ///
// /// # Returns
// /// A tuple of three Strings: (all_count, file_count, dir_count)
// /// - `all_count`: Total number of items (files + dirs + symlinks + special files)
// /// - `file_count`: Number of regular files only
// /// - `dir_count`: Number of directories only
// ///
// /// # Error Handling
// /// Returns ("?", "?", "?") if any error occurs:
// /// - Directory cannot be read (permissions, doesn't exist, etc.)
// /// - Metadata cannot be accessed for items
// /// - Counter overflow (practically impossible with u128)
// /// - String conversion fails
// /// - Any other I/O error
// ///
// /// This fail-safe approach ensures the TUI continues to function even if
// /// counting fails, displaying "?" to indicate unknown counts.
// ///
// /// # Scope
// /// - Counts ONLY items in the specified directory (flat, non-recursive)
// /// - Includes hidden files and directories (those starting with '.')
// /// - Includes ALL item types (files, dirs, symlinks, FIFOs, sockets, etc.)
// /// - Does NOT follow symlinks or recurse into subdirectories
// ///
// /// # Item Classification
// /// - Files: Regular files only
// /// - Directories: Directories only
// /// - All: Everything else goes into 'all' count only (symlinks, FIFOs, etc.)
// ///
// /// # Loop Safety
// /// The iterator from fs::read_dir() is naturally bounded by the number of
// /// entries in the directory. This is not an unbounded loop - it will terminate
// /// when the directory runs out of entries, similar to iterating over an array.
// ///
// /// # Examples
// /// ```rust
// /// let path = PathBuf::from("/home/user/documents");
// /// let (all, files, dirs) = count_directory_items(&path);
// /// println!("Total: {}, Files: {}, Directories: {}", all, files, dirs);
// /// // Output: "Total: 42, Files: 35, Directories: 7"
// ///
// /// // On error:
// /// let bad_path = PathBuf::from("/nonexistent");
// /// let (all, files, dirs) = count_directory_items(&bad_path);
// /// // Returns: ("?", "?", "?")
// /// ```
// fn count_directory_items(path: &PathBuf) -> (String, String, String) {
//     // Error handling: Path validation (defensive check)
//     // Check if path is empty - could indicate an error condition
//     if path.as_os_str().is_empty() {
//         // Path is empty - return error indicators
//         return (String::from("?"), String::from("?"), String::from("?"));
//     }

//     // Initialize counters with u128 for maximum range
//     let mut all_count: u128 = 0;
//     let mut file_count: u128 = 0;
//     let mut dir_count: u128 = 0;

//     // Attempt to read directory contents
//     // Error handling: Cannot read directory
//     let directory_reader = match fs::read_dir(path) {
//         Ok(reader) => reader,
//         Err(_) => {
//             // Cannot read directory - return unknowns
//             // Common causes: permission denied, path doesn't exist, not a directory
//             return (String::from("?"), String::from("?"), String::from("?"));
//         }
//     };

//     // Iterate through directory entries
//     // The iterator is naturally bounded by the filesystem - it will terminate
//     // when the directory runs out of entries (not an infinite loop)
//     for entry_result in directory_reader {
//         // Error handling: Reading directory entry
//         let entry = match entry_result {
//             Ok(e) => e,
//             Err(_) => {
//                 // Error reading this specific entry - skip it
//                 // This can happen with corrupted entries or permission issues
//                 continue;
//             }
//         };

//         // Error handling: Getting metadata for entry
//         let metadata = match entry.metadata() {
//             Ok(meta) => meta,
//             Err(_) => {
//                 // Cannot read metadata for this entry - skip it
//                 // Can occur with broken symlinks or permission issues
//                 continue;
//             }
//         };

//         // Error handling: Counter overflow protection
//         // Count this item in 'all' using checked arithmetic
//         all_count = match all_count.checked_add(1) {
//             Some(count) => count,
//             None => {
//                 // Overflow detected - directory has > 340 undecillion items
//                 // This should never happen in practice, but handle it anyway
//                 return (String::from("?"), String::from("?"), String::from("?"));
//             }
//         };

//         // Classify the item type
//         if metadata.is_file() {
//             // Error handling: File counter overflow
//             file_count = match file_count.checked_add(1) {
//                 Some(count) => count,
//                 None => {
//                     // Overflow on file count
//                     return (String::from("?"), String::from("?"), String::from("?"));
//                 }
//             };
//         } else if metadata.is_dir() {
//             // Error handling: Directory counter overflow
//             dir_count = match dir_count.checked_add(1) {
//                 Some(count) => count,
//                 None => {
//                     // Overflow on directory count
//                     return (String::from("?"), String::from("?"), String::from("?"));
//                 }
//             };
//         }
//         // Note: Symlinks, FIFOs, sockets, etc. are counted only in 'all'
//         // They increment all_count but not file_count or dir_count
//     }

//     // Error handling: Logic consistency check with overflow protection
//     // Use checked_add to prevent overflow in the comparison itself
//     let files_plus_dirs = match file_count.checked_add(dir_count) {
//         Some(sum) => sum,
//         None => {
//             // Overflow when adding file_count + dir_count
//             // This means the counts are corrupted somehow
//             return (String::from("?"), String::from("?"), String::from("?"));
//         }
//     };

//     // Safely check if files + dirs exceeds all_count
//     if files_plus_dirs > all_count {
//         // Logic error detected - counts are inconsistent
//         // This should never happen, but if it does, return error indicators
//         return (String::from("?"), String::from("?"), String::from("?"));
//     }

//     // Convert counts to strings
//     // Note: to_string() on integers is infallible, but we're defensive
//     let all_str = all_count.to_string();
//     let file_str = file_count.to_string();
//     let dir_str = dir_count.to_string();

//     // Final sanity check: Ensure strings are valid
//     // This is defensive - to_string() on integers should never fail
//     if all_str.is_empty() || file_str.is_empty() || dir_str.is_empty() {
//         return (String::from("?"), String::from("?"), String::from("?"));
//     }

//     (all_str, file_str, dir_str)
// }

/// Determines starting location (file and/or directory) from command line arguments
///
/// # Project Context
/// File Fantastic needs flexible launching:
/// - `ff` → Start browsing current directory
/// - `ff /some/dir` → Start browsing that directory
/// - `ff /some/file.txt` → Open file in Lines, then browse parent directory
///
/// This function analyzes the first command line argument and determines:
/// 1. Whether a file should be opened in Lines editor
/// 2. Which directory FF should start browsing in
///
/// # Returns
/// * `Ok(StartingLocation)` - Success with optional file and required directory
/// * `Err(FileFantasticError)` - Only if current directory cannot be determined (critical failure)
///
/// # Behavior by Input
/// | User Input | `file_to_open` | `directory_to_browse` | Notes |
/// |------------|----------------|----------------------|--------|
/// | No args | `None` | Current directory | Standard launch |
/// | Valid directory | `None` | That directory (absolute) | Browse specific dir |
/// | Valid file | `Some(file)` | Parent directory (absolute) | Edit then browse |
/// | Invalid path | `None` | Current directory | Fallback with warning |
///
/// # Path Handling
/// - All returned paths are converted to absolute paths for clarity
/// - Relative paths in arguments are resolved against current directory
/// - Symbolic links are preserved (not resolved) for user clarity
/// - Parent directory extraction for files is validated
///
/// # Error Handling & Defensive Programming
/// - Only returns `Err` if current directory cannot be determined (critical system issue)
/// - All other failures result in safe fallback to current directory
/// - Invalid paths trigger warning message and fallback (not error)
/// - Missing parent directory (rare edge case) triggers fallback
/// - Debug builds show detailed diagnostics via `#[cfg(debug_assertions)]`
/// - Production builds show user-friendly warnings only
///
/// # Security & Safety
/// - No interactive prompts (no stdin usage) - pure function
/// - No path disclosure in production error messages
/// - No unsafe code or unwrap/expect calls
/// - Validates existence before returning paths
/// - Defensive checks against permission issues
///
/// # Examples
/// ```rust,ignore
/// // No arguments - use current directory
/// let loc = get_starting_path_dir_or_file_from_args_or_cwd_default()?;
/// assert_eq!(loc.file_to_open, None);
/// assert!(loc.directory_to_browse.is_absolute());
///
/// // Directory argument
/// // $ ff /home/user/projects
/// let loc = get_starting_path_dir_or_file_from_args_or_cwd_default()?;
/// assert_eq!(loc.file_to_open, None);
/// assert_eq!(loc.directory_to_browse, PathBuf::from("/home/user/projects"));
///
/// // File argument
/// // $ ff /home/user/projects/readme.txt
/// let loc = get_starting_path_dir_or_file_from_args_or_cwd_default()?;
/// assert_eq!(loc.file_to_open, Some(PathBuf::from("/home/user/projects/readme.txt")));
/// assert_eq!(loc.directory_to_browse, PathBuf::from("/home/user/projects"));
/// ```
fn get_starting_path_dir_or_file_from_args_or_cwd_default() -> Result<StartingLocation> {
    // =================================================
    // Debug-Assert: Validate std::env::args exists
    // =================================================
    // This should never fail in normal Rust programs, but defensive check
    debug_assert!(
        std::env::args().len() >= 1,
        "std::env::args() should always have at least program name"
    );

    // Get command line arguments (skip program name)
    let args: Vec<String> = std::env::args().skip(1).collect();

    // =================================================
    // Case 1: No Arguments Provided
    // =================================================
    if args.is_empty() {
        // No arguments - use current directory, no file to open
        #[cfg(debug_assertions)]
        eprintln!("[DEBUG] No arguments provided, using current directory");

        let current_dir = std::env::current_dir().map_err(|e| {
            // Critical failure - cannot determine current directory
            // This is the only scenario where we return an error
            #[cfg(debug_assertions)]
            eprintln!("[DEBUG] Failed to get current directory: {}", e);

            FileFantasticError::Io(e)
        })?;

        return Ok(StartingLocation {
            file_to_open: None,
            directory_to_browse: current_dir,
        });
    }

    // =================================================
    // Case 2: Argument Provided - Parse Path
    // =================================================
    let path_arg = PathBuf::from(&args[0]);

    #[cfg(debug_assertions)]
    eprintln!("[DEBUG] Argument provided: {}", path_arg.display());

    // =================================================
    // Convert to Absolute Path
    // =================================================
    // Convert relative paths to absolute for clarity and consistency
    let absolute_path = if path_arg.is_relative() {
        #[cfg(debug_assertions)]
        eprintln!("[DEBUG] Path is relative, converting to absolute");

        // Get current directory to resolve relative path
        let current_dir = match std::env::current_dir() {
            Ok(dir) => dir,
            Err(e) => {
                // Cannot determine current directory - critical failure
                #[cfg(debug_assertions)]
                eprintln!(
                    "[DEBUG] Failed to get current directory for relative path resolution: {}",
                    e
                );

                return Err(FileFantasticError::Io(e));
            }
        };

        // Join current directory with relative path
        current_dir.join(&path_arg)
    } else {
        // Already absolute, use as-is
        path_arg
    };

    #[cfg(debug_assertions)]
    eprintln!("[DEBUG] Absolute path: {}", absolute_path.display());

    // =================================================
    // Case 3: Check if Path Exists
    // =================================================
    if !absolute_path.exists() {
        // Path doesn't exist - fall back to current directory
        println!(
            "Warning: Path '{}' does not exist. Starting in current directory.",
            absolute_path.display()
        );

        #[cfg(debug_assertions)]
        eprintln!("[DEBUG] Path does not exist, falling back to current directory");

        // Get current directory as fallback
        let fallback_dir = match std::env::current_dir() {
            Ok(dir) => dir,
            Err(e) => {
                // Cannot get current directory - critical failure
                #[cfg(debug_assertions)]
                eprintln!(
                    "[DEBUG] Failed to get current directory for fallback: {}",
                    e
                );

                return Err(FileFantasticError::Io(e));
            }
        };

        return Ok(StartingLocation {
            file_to_open: None,
            directory_to_browse: fallback_dir,
        });
    }

    // =================================================
    // Case 4: Path Exists - Determine Type
    // =================================================

    if absolute_path.is_dir() {
        // =================================================
        // Case 4a: Path is a Directory
        // =================================================
        #[cfg(debug_assertions)]
        eprintln!("[DEBUG] Path is a directory");

        return Ok(StartingLocation {
            file_to_open: None,
            directory_to_browse: absolute_path,
        });
    } else {
        // =================================================
        // Case 4b: Path is a File (or other non-directory)
        // =================================================
        #[cfg(debug_assertions)]
        eprintln!("[DEBUG] Path is a file");

        // Notify user about file opening and parent directory usage
        println!("Opening file: {}", absolute_path.display());

        // Extract parent directory to use as browsing directory
        match absolute_path.parent() {
            Some(parent) => {
                #[cfg(debug_assertions)]
                eprintln!("[DEBUG] Using parent directory: {}", parent.display());

                println!("Starting directory: {}", parent.display());

                // Return file to open and parent directory to browse
                Ok(StartingLocation {
                    file_to_open: Some(absolute_path.clone()),
                    directory_to_browse: PathBuf::from(parent),
                })
            }
            None => {
                // No parent directory (rare edge case: root-level file, special paths)
                // Fall back to current directory
                println!(
                    "Warning: Cannot determine parent directory of '{}'. Starting in current directory.",
                    absolute_path.display()
                );

                #[cfg(debug_assertions)]
                eprintln!(
                    "[DEBUG] Cannot determine parent directory, falling back to current directory"
                );

                // Get current directory as fallback
                let fallback_dir = match std::env::current_dir() {
                    Ok(dir) => dir,
                    Err(e) => {
                        // Cannot get current directory - critical failure
                        #[cfg(debug_assertions)]
                        eprintln!(
                            "[DEBUG] Failed to get current directory for fallback: {}",
                            e
                        );

                        return Err(FileFantasticError::Io(e));
                    }
                };

                // File exists but we can't use it (no parent) - return no file to open
                Ok(StartingLocation {
                    file_to_open: None,
                    directory_to_browse: fallback_dir,
                })
            }
        }
    }
}

// =================================================
// Tests
// =================================================
#[cfg(test)]
mod tests_starting_location {
    use super::*;
    // use std::fs;

    /// Test: No arguments returns current directory with no file
    ///
    /// # Project Context
    /// Default FF launch behavior - start browsing current directory
    #[test]
    fn test_no_arguments_returns_current_dir() {
        // This test can only work if we can get current directory
        let current_dir = match std::env::current_dir() {
            Ok(dir) => dir,
            Err(_) => {
                // Skip test if we can't determine current directory
                println!("Skipping test - cannot determine current directory");
                return;
            }
        };

        // Note: This test would need to mock std::env::args()
        // For now, this is a template for integration testing
        // In actual test, we'd capture current directory and verify
        assert!(current_dir.is_absolute());
    }

    /// Test: Absolute path conversion for relative paths
    ///
    /// # Project Context
    /// FF must always work with absolute paths for clarity and consistency
    #[test]
    fn test_relative_path_converted_to_absolute() {
        let relative_path = PathBuf::from(".");

        // Get current directory
        let current_dir = match std::env::current_dir() {
            Ok(dir) => dir,
            Err(_) => {
                println!("Skipping test - cannot determine current directory");
                return;
            }
        };

        // Verify relative path can be made absolute
        let absolute = if relative_path.is_relative() {
            current_dir.join(&relative_path)
        } else {
            relative_path
        };

        assert!(absolute.is_absolute());
    }

    /// Test: Parent directory extraction from file path
    ///
    /// # Project Context
    /// When FF is launched with a file, it needs the parent directory for browsing
    #[test]
    fn test_parent_directory_extraction() {
        // Create a test path structure
        let test_file = PathBuf::from("/home/user/documents/test.txt");

        // Extract parent
        let parent = test_file.parent();

        // Verify parent exists and is correct
        assert!(parent.is_some());
        assert_eq!(parent.unwrap(), PathBuf::from("/home/user/documents"));
    }

    /// Test: Root file edge case (file with no parent)
    ///
    /// # Project Context
    /// Defensive programming - handle edge cases that shouldn't happen but might
    #[test]
    fn test_root_file_edge_case() {
        // On Unix: /file.txt has parent /
        // On Windows: C:\file.txt has parent C:\
        // But some paths might not have logical parents

        let root_file = if cfg!(windows) {
            PathBuf::from("C:\\")
        } else {
            PathBuf::from("/")
        };

        // Root should either have no parent or parent is itself
        let parent = root_file.parent();

        // This is defensive - we handle both cases in production code
        if let Some(_parent_path) = parent {
            // Has a parent (even if it's root)
            assert!(true);
        } else {
            // No parent - our code handles this with fallback
            assert!(true);
        }
    }

    /// Test: Path existence validation
    ///
    /// # Project Context
    /// FF must validate paths before attempting to use them
    #[test]
    fn test_path_existence_check() {
        // Test with current directory (should always exist)
        let current_dir = match std::env::current_dir() {
            Ok(dir) => dir,
            Err(_) => {
                println!("Skipping test - cannot determine current directory");
                return;
            }
        };

        assert!(current_dir.exists());
        assert!(current_dir.is_dir());
    }

    /// Test: File vs directory distinction
    ///
    /// # Project Context
    /// FF behavior differs based on whether argument is file or directory
    #[test]
    fn test_file_vs_directory_distinction() {
        // Get current directory (should be a directory)
        let current_dir = match std::env::current_dir() {
            Ok(dir) => dir,
            Err(_) => {
                println!("Skipping test - cannot determine current directory");
                return;
            }
        };

        // Current directory should be a directory, not a file
        assert!(current_dir.is_dir());
        assert!(!current_dir.is_file());
    }

    /// Test-Assert: StartingLocation struct field validation
    ///
    /// # Project Context
    /// Validate struct guarantees at test time
    #[test]
    fn test_starting_location_struct_guarantees() {
        // Create a test instance
        let location = StartingLocation {
            file_to_open: None,
            directory_to_browse: PathBuf::from("/test/path"),
        };

        // Verify struct fields are accessible
        assert_eq!(location.file_to_open, None);
        assert_eq!(location.directory_to_browse, PathBuf::from("/test/path"));

        // Test with file
        let location_with_file = StartingLocation {
            file_to_open: Some(PathBuf::from("/test/file.txt")),
            directory_to_browse: PathBuf::from("/test"),
        };

        assert!(location_with_file.file_to_open.is_some());
        assert_eq!(
            location_with_file.file_to_open.unwrap(),
            PathBuf::from("/test/file.txt")
        );
    }

    /// Integration Test Template: End-to-end argument processing
    ///
    /// # Project Context
    /// Full workflow test - argument parsing through to StartingLocation
    ///
    /// # Note
    /// This is a template - actual integration tests would need to:
    /// 1. Create temporary test directories and files
    /// 2. Mock command line arguments
    /// 3. Call get_starting_path_dir_or_file_from_args_or_cwd_default()
    /// 4. Verify returned StartingLocation
    #[test]
    fn test_integration_template() {
        // Template for integration testing
        // Would need temp directory setup:
        // let temp_dir = std::env::temp_dir();
        // let test_file = temp_dir.join("test_file.txt");
        // fs::write(&test_file, "test content")?;

        // Then test function with various scenarios
        assert!(true); // Placeholder
    }
}

// /// Determines the starting directory path from command line arguments
// ///
// /// # Returns
// /// * `Result<PathBuf>` - The absolute path to start in or error with context
// ///
// /// # Behavior
// /// - If a valid path is provided as first argument, uses that
// /// - If a file path is provided, uses its parent directory
// /// - If path doesn't exist or no args provided, uses current directory
// /// - Converts all paths to absolute paths for clarity
// ///
// /// # Error Handling
// /// - Validates path existence and type
// /// - Provides clear error messages for invalid paths
// /// - Falls back to current directory when appropriate
// /// - Handles failures to determine current or parent directories
// fn get_starting_path_from_args_or_cwd_default() -> Result<PathBuf> {
//     // Get command line arguments
//     let args: Vec<String> = std::env::args().skip(1).collect();

//     if args.is_empty() {
//         // No arguments provided, use current directory
//         return std::env::current_dir().map_err(|e| {
//             eprintln!("Failed to get current directory: {}", e);
//             FileFantasticError::Io(e)
//         });
//     }

//     // Use first argument as path
//     let path_arg = PathBuf::from(&args[0]);

//     // Convert to absolute path if possible
//     let absolute_path = if path_arg.is_relative() {
//         // Join with current directory to make absolute
//         match std::env::current_dir() {
//             Ok(current_dir) => current_dir.join(&path_arg),
//             Err(e) => {
//                 eprintln!("Failed to get current directory: {}", e);
//                 return Err(FileFantasticError::Io(e));
//             }
//         }
//     } else {
//         path_arg
//     };

//     if absolute_path.exists() {
//         if absolute_path.is_dir() {
//             // Path is a directory, use it directly
//             Ok(absolute_path)
//         } else {
//             // Path is a file, use its parent directory
//             match absolute_path.parent() {
//                 Some(parent) => {
//                     // Print notice about using parent directory
//                     println!(
//                         "Note: Using parent directory of file: {}",
//                         absolute_path.display()
//                     );
//                     println!("Directory: {}", parent.display());
//                     println!("Press Enter to continue...");
//                     let mut input = String::new();
//                     io::stdin().read_line(&mut input).map_err(|e| {
//                         eprintln!("Failed to read input: {}", e);
//                         FileFantasticError::Io(e)
//                     })?;

//                     Ok(PathBuf::from(parent))
//                 }
//                 None => {
//                     // This should rarely happen (e.g., with root files on Windows)
//                     eprintln!(
//                         "Cannot determine parent directory of '{}'",
//                         absolute_path.display()
//                     );
//                     Err(FileFantasticError::InvalidName(
//                         absolute_path.display().to_string(),
//                     ))
//                 }
//             }
//         }
//     } else {
//         // Path doesn't exist, notify user and fall back to current directory
//         eprintln!(
//             "Warning: Path '{}' does not exist. Starting in current directory.",
//             absolute_path.display()
//         );
//         std::env::current_dir().map_err(|e| {
//             eprintln!("Failed to get current directory: {}", e);
//             FileFantasticError::Io(e)
//         })
//     }
// }