Refactor: Consolidate caching patterns into shared LocatorCache abstraction (#301)

- [x] Create a new `LocatorCache<K, V>` generic caching abstraction in
`pet-core`
- [x] Add `get()`, `get_or_insert_with()`, `insert()`, `contains_key()`,
`clear()`, `values()`, `len()`, `is_empty()`, and `clone_map()` methods
- [x] Create type aliases `EnvironmentCache` and `ManagerCache` for
common uses
- [x] Refactor `pet-conda` to use the new cache abstraction
- [x] Refactor `pet-linux-global-python` to use the new cache
abstraction
- [x] Run tests to verify the changes work correctly
- [x] Request code review
- [x] Run CodeQL security checker
- [x] Address PR review feedback:
- [x] Add `insert_many()` method for atomic batch inserts (addresses
lock granularity concern)
  - [x] Add `#[must_use]` attribute to `get_or_insert_with()`
- [x] Update `pet-linux-global-python` to use `insert_many()` for
symlinks + executable

## Summary

This PR introduces a generic `LocatorCache<K, V>` abstraction in the
`pet-core` crate that consolidates the common caching patterns used
across multiple locators. The cache provides:

1. Thread-safe operations using `RwLock`
2. Efficient read access with separate read/write locks
3. Double-check locking in `get_or_insert_with()` to prevent redundant
computation
4. Atomic batch inserts via `insert_many()` for better lock efficiency
5. Type aliases for common use cases (`EnvironmentCache`,
`ManagerCache`)

## Security Summary

No security vulnerabilities were discovered by CodeQL analysis.

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>Refactor: Consolidate caching patterns across locators
into a shared abstraction</issue_title>
> <issue_description>## Summary
> Multiple locators implement nearly identical caching patterns for
environments and managers. Consolidating these into a shared abstraction
would reduce code duplication and ensure consistent behavior.
> 
> ## Current Duplicate Patterns
> 
> ### Pattern: Cache with mutex + contains_key check
> Found in:
> - `crates/pet-conda/src/lib.rs`
> - `crates/pet-poetry/src/lib.rs`
> - `crates/pet-windows-store/src/lib.rs`
> - `crates/pet-linux-global-python/src/lib.rs`
> 
> ```rust
> // This pattern appears in multiple files:
> pub struct SomeLocator {
>     environments: Arc<Mutex<HashMap<PathBuf, PythonEnvironment>>>,
> }
> 
> impl SomeLocator {
>     fn find_with_cache(&self) -> Option<...> {
>         let environments = self.environments.lock().unwrap();
>         if environments.contains_key(&key) {
>             return Some(environments.get(&key).unwrap().clone());
>         }
>         // ... compute and cache
>     }
>     
>     fn clear(&self) {
>         self.environments.lock().unwrap().clear();
>     }
> }
> ```
> 
> ## Proposed Solution
> 
> ### Create a generic caching wrapper
> ```rust
> // In pet-core or a new pet-cache crate
> pub struct LocatorCache<K, V> {
>     cache: RwLock<HashMap<K, V>>,
> }
> 
> impl<K: Eq + Hash, V: Clone> LocatorCache<K, V> {
>     pub fn new() -> Self {
>         Self { cache: RwLock::new(HashMap::new()) }
>     }
>     
>     pub fn get(&self, key: &K) -> Option<V> {
>         self.cache.read().unwrap().get(key).cloned()
>     }
>     
>     pub fn get_or_insert_with<F>(&self, key: K, f: F) -> V
>     where
>         F: FnOnce() -> Option<V>,
>     {
>         // Check read lock first
>         if let Some(v) = self.cache.read().unwrap().get(&key) {
>             return v.clone();
>         }
>         // Upgrade to write lock and compute
>         if let Some(value) = f() {
>             self.cache.write().unwrap().insert(key, value.clone());
>             value
>         }
>     }
>     
>     pub fn clear(&self) {
>         self.cache.write().unwrap().clear();
>     }
> }
> 
> // Type aliases for common uses
> pub type EnvironmentCache = LocatorCache<PathBuf, PythonEnvironment>;
> pub type ManagerCache = LocatorCache<PathBuf, EnvManager>;
> ```
> 
> ### Usage in locators
> ```rust
> pub struct Conda {
>     pub environments: EnvironmentCache,
>     pub managers: ManagerCache,
>     // ...
> }
> 
> impl Conda {
>     fn try_from(&self, env: &PythonEnv) -> Option<PythonEnvironment> {
>         self.environments.get_or_insert_with(path.clone(), || {
>             // compute environment
>         })
>     }
> }
> ```
> 
> ## Benefits
> 1. **Consistency**: All locators behave the same way
> 2. **Less code**: Remove duplicate boilerplate
> 3. **Centralized improvements**: RwLock upgrade, better error
handling, etc. benefit all locators
> 4. **Testability**: Cache behavior can be tested once
> 
> ## Priority
> Low - Requires significant refactoring but improves maintainability
long-term.</issue_description>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> </comments>
> 


</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #291

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in
our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: karthiknadig <3840081+karthiknadig@users.noreply.github.com>

Author: Copilot

crates/pet-conda/src/lib.rs

@@ -11,6 +11,7 @@ use environments::{get_conda_environment_info, CondaEnvironment};
 use log::error;
 use manager::CondaManager;
 use pet_core::{
+    cache::LocatorCache,
     env::PythonEnv,
     os_environment::Environment,
     python_environment::{PythonEnvironment, PythonEnvironmentKind},
@@ -21,7 +22,6 @@ use pet_fs::path::norm_case;
 use rayon::prelude::*;
 use serde::{Deserialize, Serialize};
 use std::{
-    collections::HashMap,
     path::{Path, PathBuf},
     sync::{Arc, RwLock},
     thread,
@@ -62,24 +62,24 @@ pub struct CondaTelemetryInfo {
 }
 
 pub struct Conda {
-    pub environments: Arc<RwLock<HashMap<PathBuf, PythonEnvironment>>>,
-    pub managers: Arc<RwLock<HashMap<PathBuf, CondaManager>>>,
+    pub environments: Arc<LocatorCache<PathBuf, PythonEnvironment>>,
+    pub managers: Arc<LocatorCache<PathBuf, CondaManager>>,
     pub env_vars: EnvVariables,
     conda_executable: Arc<RwLock<Option<PathBuf>>>,
 }
 
 impl Conda {
     pub fn from(env: &dyn Environment) -> Conda {
         Conda {
-            environments: Arc::new(RwLock::new(HashMap::new())),
-            managers: Arc::new(RwLock::new(HashMap::new())),
+            environments: Arc::new(LocatorCache::new()),
+            managers: Arc::new(LocatorCache::new()),
             env_vars: EnvVariables::from(env),
             conda_executable: Arc::new(RwLock::new(None)),
         }
     }
     fn clear(&self) {
-        self.environments.write().unwrap().clear();
-        self.managers.write().unwrap().clear();
+        self.environments.clear();
+        self.managers.clear();
     }
 }
 
@@ -92,17 +92,17 @@ impl CondaLocator for Conda {
         // Look for environments that we couldn't find without spawning conda.
         let user_provided_conda_exe = conda_executable.is_some();
         let conda_info = CondaInfo::from(conda_executable)?;
-        let environments = self.environments.read().unwrap().clone();
+        let environments_map = self.environments.clone_map();
         let new_envs = conda_info
             .envs
             .clone()
             .into_iter()
-            .filter(|p| !environments.contains_key(p))
+            .filter(|p| !environments_map.contains_key(p))
             .collect::<Vec<PathBuf>>();
         if new_envs.is_empty() {
             return None;
         }
-        let environments = environments
+        let environments = environments_map
             .into_values()
             .collect::<Vec<PythonEnvironment>>();
 
@@ -120,10 +120,7 @@ impl CondaLocator for Conda {
 
     fn get_info_for_telemetry(&self, conda_executable: Option<PathBuf>) -> CondaTelemetryInfo {
         let can_spawn_conda = CondaInfo::from(conda_executable).is_some();
-        let environments = self.environments.read().unwrap().clone();
-        let environments = environments
-            .into_values()
-            .collect::<Vec<PythonEnvironment>>();
+        let environments = self.environments.values();
         let (conda_rcs, env_dirs) = get_conda_rcs_and_env_dirs(&self.env_vars, &environments);
         let mut environments_txt = None;
         let mut environments_txt_exists = None;
@@ -160,19 +157,14 @@ impl CondaLocator for Conda {
             if let Some(conda_dir) = manager.conda_dir.clone() {
                 // Keep track to search again later.
                 // Possible we'll find environments in other directories created using this manager
-                let mut managers = self.managers.write().unwrap();
-                // Keep track to search again later.
-                // Possible we'll find environments in other directories created using this manager
-                managers.insert(conda_dir.clone(), manager.clone());
-                drop(managers);
+                self.managers.insert(conda_dir.clone(), manager.clone());
 
                 // Find all the environments in the conda install folder. (under `envs` folder)
                 for conda_env in
                     get_conda_environments(&get_environments(&conda_dir), &manager.clone().into())
                 {
                     // If reported earlier, no point processing this again.
-                    let mut environments = self.environments.write().unwrap();
-                    if environments.contains_key(&conda_env.prefix) {
+                    if self.environments.contains_key(&conda_env.prefix) {
                         continue;
                     }
 
@@ -184,7 +176,8 @@ impl CondaLocator for Conda {
                         .and_then(|p| CondaManager::from(&p))
                         .unwrap_or(manager.clone());
                     let env = conda_env.to_python_environment(Some(manager.to_manager()));
-                    environments.insert(conda_env.prefix.clone(), env.clone());
+                    self.environments
+                        .insert(conda_env.prefix.clone(), env.clone());
                     reporter.report_manager(&manager.to_manager());
                     reporter.report_environment(&env);
                 }
@@ -195,22 +188,8 @@ impl CondaLocator for Conda {
 
 impl Conda {
     fn get_manager(&self, conda_dir: &Path) -> Option<CondaManager> {
-        // First try to read from cache
-        {
-            let managers = self.managers.read().unwrap();
-            if let Some(mgr) = managers.get(conda_dir) {
-                return Some(mgr.clone());
-            }
-        }
-
-        // If not found, acquire write lock and insert
-        if let Some(manager) = CondaManager::from(conda_dir) {
-            let mut managers = self.managers.write().unwrap();
-            managers.insert(conda_dir.into(), manager.clone());
-            Some(manager)
-        } else {
-            None
-        }
+        self.managers
+            .get_or_insert_with(conda_dir.to_path_buf(), || CondaManager::from(conda_dir))
     }
 }
 
@@ -251,29 +230,25 @@ impl Locator for Conda {
                 return None;
             }
 
-            // First check cache with read lock
-            {
-                let environments = self.environments.read().unwrap();
-                if let Some(env) = environments.get(path) {
-                    return Some(env.clone());
-                }
+            // Check cache first
+            if let Some(cached_env) = self.environments.get(path) {
+                return Some(cached_env);
             }
-            // Not in cache, build the environment and insert with write lock
+
+            // Not in cache, build the environment and insert
             if let Some(env) = get_conda_environment_info(path, &None) {
                 if let Some(conda_dir) = &env.conda_dir {
                     if let Some(manager) = self.get_manager(conda_dir) {
                         let env = env.to_python_environment(Some(manager.to_manager()));
-                        let mut environments = self.environments.write().unwrap();
-                        environments.insert(path.clone(), env.clone());
+                        self.environments.insert(path.clone(), env.clone());
                         return Some(env);
                     } else {
                         // We will still return the conda env even though we do not have the manager.
                         // This might seem incorrect, however the tool is about discovering environments.
                         // The client can activate this env either using another conda manager or using the activation scripts
                         error!("Unable to find Conda Manager for env (even though we have a conda_dir): {:?}", env);
                         let env = env.to_python_environment(None);
-                        let mut environments = self.environments.write().unwrap();
-                        environments.insert(path.clone(), env.clone());
+                        self.environments.insert(path.clone(), env.clone());
                         return Some(env);
                     }
                 } else {
@@ -282,8 +257,7 @@ impl Locator for Conda {
                     // The client can activate this env either using another conda manager or using the activation scripts
                     error!("Unable to find Conda Manager for env: {:?}", env);
                     let env = env.to_python_environment(None);
-                    let mut environments = self.environments.write().unwrap();
-                    environments.insert(path.clone(), env.clone());
+                    self.environments.insert(path.clone(), env.clone());
                     return Some(env);
                 }
             }
@@ -316,8 +290,7 @@ impl Locator for Conda {
                         error!("Unable to find Conda Manager for the Conda env: {:?}", env);
                         let prefix = env.prefix.clone();
                         let env = env.to_python_environment(None);
-                        let mut environments = self.environments.write().unwrap();
-                        environments.insert(prefix, env.clone());
+                        self.environments.insert(prefix, env.clone());
                         reporter.report_environment(&env);
                         return None;
                     }
@@ -326,38 +299,23 @@ impl Locator for Conda {
                     // We will try to get the manager for this conda_dir
                     let prefix = env.clone().prefix.clone();
 
-                    {
-                        // 3.1 Check if we have already reported this environment.
-                        // Closure to quickly release lock
-                        let environments = self.environments.read().unwrap();
-                        if environments.contains_key(&env.prefix) {
-                            return None;
-                        }
+                    // 3.1 Check if we have already reported this environment.
+                    if self.environments.contains_key(&env.prefix) {
+                        return None;
                     }
 
-
                     // 4 Get the manager for this env.
                     let conda_dir = &env.conda_dir.clone()?;
-                    let managers = self.managers.read().unwrap();
-                    let mut manager = managers.get(conda_dir).cloned();
-                    drop(managers);
-
-                    if manager.is_none() {
-                        // 4.1 Build the manager from the conda dir if we do not have it.
-                        if let Some(conda_manager) = CondaManager::from(conda_dir) {
-                            let mut managers = self.managers.write().unwrap();
-                            managers.insert(conda_dir.to_path_buf().clone(), conda_manager.clone());
-                            manager = Some(conda_manager);
-                        }
-                    }
+                    let manager = self.managers.get_or_insert_with(conda_dir.clone(), || {
+                        CondaManager::from(conda_dir)
+                    });
 
                     // 5. Report this env.
                     if let Some(manager) = manager {
                         let env = env.to_python_environment(
                             Some(manager.to_manager()),
                         );
-                        let mut environments = self.environments.write().unwrap();
-                        environments.insert(prefix.clone(), env.clone());
+                        self.environments.insert(prefix.clone(), env.clone());
                         reporter.report_manager(&manager.to_manager());
                         reporter.report_environment(&env);
                     } else {
@@ -366,8 +324,7 @@ impl Locator for Conda {
                         // The client can activate this env either using another conda manager or using the activation scripts
                         error!("Unable to find Conda Manager for Conda env (even though we have a conda_dir {:?}): Env Details = {:?}", conda_dir, env);
                         let env = env.to_python_environment(None);
-                        let mut environments = self.environments.write().unwrap();
-                        environments.insert(prefix.clone(), env.clone());
+                        self.environments.insert(prefix.clone(), env.clone());
                         reporter.report_environment(&env);
                     }
                     Option::<()>::Some(())