fix: rename passThroughEnvs to untrackedEnv (#226)

## Key Changes

- **Configuration fields**: Renamed `pass_through_envs` to
`untracked_env` in:
  - `EnvConfig` and related structures
  - `EnabledCacheConfig` user configuration
  - `EnvFingerprints` struct
  - All snapshot test fixtures

- **Constants and defaults**: Updated `DEFAULT_PASSTHROUGH_ENVS` to
`DEFAULT_UNTRACKED_ENV`

- **Cache fingerprint tracking**: Renamed `pass_through_env_config` to
`untracked_env_config` in fingerprint structures

- **Display and error messages**: Updated all user-facing messages and
enum variants:
  - `PassThroughEnvAdded` → `UntrackedEnvAdded`
  - `PassThroughEnvRemoved` → `UntrackedEnvRemoved`
- Error messages now reference "untracked env" instead of "pass-through
env"

- **Documentation and comments**: Updated all comments, docs, and
TypeScript type definitions to use the new terminology

- **Test fixtures**: Updated all snapshot files and test configuration
files to reflect the new naming

Co-authored-by: Claude <noreply@anthropic.com>

Author: branchseer

CLAUDE.md

@@ -133,7 +133,7 @@ Tasks are defined in `vite-task.json`:
       "dependsOn": ["build", "package#task"],
       "cache": true,
       "env": ["NODE_ENV"],
-      "passThroughEnvs": ["CI"],
+      "untrackedEnv": ["CI"],
       "input": ["src/**", "!dist/**", { "auto": true }]
     }
   }
@@ -146,7 +146,7 @@ Tasks are defined in `vite-task.json`:
 - `dependsOn`: explicit task dependencies (`taskName` or `package#task`)
 - `cache` (task): enable/disable caching for this task (default: `true`)
 - `env`: env var names to fingerprint and pass to the task
-- `passThroughEnvs`: env var names to pass without fingerprinting
+- `untrackedEnv`: env var names to pass without fingerprinting
 - `input`: files for cache fingerprinting (globs, `{ "auto": true }`, negation patterns)
 
 ## Task Dependencies

crates/vite_task/docs/task-cache.md

@@ -105,7 +105,7 @@ pub struct SpawnFingerprint {
     pub cwd: RelativePathBuf,
     pub command_fingerprint: CommandFingerprint,
     pub fingerprinted_envs: BTreeMap<Str, Str>,
-    pub pass_through_envs: BTreeSet<Str>,
+    pub untracked_env: BTreeSet<Str>,
     pub fingerprint_ignores: Option<Vec<Str>>,
 }
 
@@ -124,25 +124,25 @@ This ensures cache invalidation when:
 
 - Working directory changes (package location changes)
 - Command or arguments change
-- Declared environment variables differ (pass-through envs don't affect cache)
+- Declared environment variables differ (untracked envs don't affect cache)
 - Program location changes (inside/outside workspace)
 
 ### 3. Environment Variable Impact on Cache
 
 The `fingerprinted_envs` field is crucial for cache correctness:
 
 - Only includes env vars explicitly declared in the task's `env` array
-- Does NOT include pass-through envs (PATH, CI, etc.)
+- Does NOT include untracked envs (PATH, CI, etc.)
 - These env vars become part of the cache key
 
 When a task runs:
 
-1. All env vars (including pass-through) are available to the process
+1. All env vars (including untracked) are available to the process
 2. Only declared env vars affect the cache key
 3. If a declared env var changes value, cache will miss
-4. If a pass-through env changes, cache will still hit
+4. If an untracked env changes, cache will still hit
 
-The `pass_through_envs` field stores env names (not values) — if the set of pass-through env names changes, the cache invalidates, but value changes don't.
+The `untracked_env` field stores env names (not values) — if the set of untracked env names changes, the cache invalidates, but value changes don't.
 
 ### 4. Execution Cache Key
 

crates/vite_task/docs/wildcard-env-patterns.md

@@ -32,7 +32,7 @@ This approach becomes cumbersome when dealing with multiple environment variable
 ## Non-Goals
 
 1. Full regex support (only glob-style wildcards)
-2. Wildcard patterns in `passThroughEnvs` (same as `env`)
+2. Wildcard patterns in `untrackedEnv` (same as `env`)
 3. Complex glob patterns like `{VITE,NODE}_*` (supported by wax crate)
 
 ## Proposed Solution

crates/vite_task/src/session/cache/display.rs

@@ -24,11 +24,11 @@ pub enum SpawnFingerprintChange {
     /// Environment variable value changed
     EnvValueChanged { key: Str, old_value: Str, new_value: Str },
 
-    // Pass-through env config changes
-    /// Pass-through env pattern added
-    PassThroughEnvAdded { name: Str },
-    /// Pass-through env pattern removed
-    PassThroughEnvRemoved { name: Str },
+    // Untracked env config changes
+    /// Untracked env pattern added
+    UntrackedEnvAdded { name: Str },
+    /// Untracked env pattern removed
+    UntrackedEnvRemoved { name: Str },
 
     // Command changes
     /// Program changed
@@ -55,11 +55,11 @@ pub fn format_spawn_change(change: &SpawnFingerprintChange) -> Str {
         SpawnFingerprintChange::EnvValueChanged { key, old_value, new_value } => {
             vite_str::format!("env {key} value changed from '{old_value}' to '{new_value}'")
         }
-        SpawnFingerprintChange::PassThroughEnvAdded { name } => {
-            vite_str::format!("pass-through env '{name}' added")
+        SpawnFingerprintChange::UntrackedEnvAdded { name } => {
+            vite_str::format!("untracked env '{name}' added")
         }
-        SpawnFingerprintChange::PassThroughEnvRemoved { name } => {
-            vite_str::format!("pass-through env '{name}' removed")
+        SpawnFingerprintChange::UntrackedEnvRemoved { name } => {
+            vite_str::format!("untracked env '{name}' removed")
         }
         SpawnFingerprintChange::ProgramChanged => Str::from("program changed"),
         SpawnFingerprintChange::ArgsChanged => Str::from("args changed"),
@@ -104,14 +104,14 @@ pub fn detect_spawn_fingerprint_changes(
         }
     }
 
-    // Check pass-through env config changes
-    let old_pass_through: FxHashSet<_> = old_env.pass_through_env_config.iter().collect();
-    let new_pass_through: FxHashSet<_> = new_env.pass_through_env_config.iter().collect();
-    for name in old_pass_through.difference(&new_pass_through) {
-        changes.push(SpawnFingerprintChange::PassThroughEnvRemoved { name: (*name).clone() });
+    // Check untracked env config changes
+    let old_untracked: FxHashSet<_> = old_env.untracked_env_config.iter().collect();
+    let new_untracked: FxHashSet<_> = new_env.untracked_env_config.iter().collect();
+    for name in old_untracked.difference(&new_untracked) {
+        changes.push(SpawnFingerprintChange::UntrackedEnvRemoved { name: (*name).clone() });
     }
-    for name in new_pass_through.difference(&old_pass_through) {
-        changes.push(SpawnFingerprintChange::PassThroughEnvAdded { name: (*name).clone() });
+    for name in new_untracked.difference(&old_untracked) {
+        changes.push(SpawnFingerprintChange::UntrackedEnvAdded { name: (*name).clone() });
     }
 
     // Check program changes
@@ -164,9 +164,9 @@ pub fn format_cache_status_inline(cache_status: &CacheStatus) -> Option<Str> {
                             | SpawnFingerprintChange::EnvValueChanged { .. },
                         ) => "envs changed",
                         Some(
-                            SpawnFingerprintChange::PassThroughEnvAdded { .. }
-                            | SpawnFingerprintChange::PassThroughEnvRemoved { .. },
-                        ) => "pass-through env config changed",
+                            SpawnFingerprintChange::UntrackedEnvAdded { .. }
+                            | SpawnFingerprintChange::UntrackedEnvRemoved { .. },
+                        ) => "untracked env config changed",
                         Some(SpawnFingerprintChange::ProgramChanged) => "program changed",
                         Some(SpawnFingerprintChange::ArgsChanged) => "args changed",
                         Some(SpawnFingerprintChange::CwdChanged) => "working directory changed",

crates/vite_task_bin/src/lib.rs

@@ -63,7 +63,7 @@ fn synthesize_node_modules_bin_task(
         args: args.into(),
         cache_config: UserCacheConfig::with_config(EnabledCacheConfig {
             env: None,
-            pass_through_envs: None,
+            untracked_env: None,
             input: None,
         }),
         envs: Arc::clone(envs),
@@ -128,7 +128,7 @@ impl vite_task::CommandHandler for CommandHandler {
                     cache_config: UserCacheConfig::with_config({
                         EnabledCacheConfig {
                             env: None,
-                            pass_through_envs: Some(vec![name]),
+                            untracked_env: Some(vec![name]),
                             input: None,
                         }
                     }),

crates/vite_task_bin/src/main.rs

@@ -34,7 +34,7 @@ async fn run() -> anyhow::Result<ExitStatus> {
                     cache_config: UserCacheConfig::with_config({
                         EnabledCacheConfig {
                             env: Some(Box::from([Str::from("FOO")])),
-                            pass_through_envs: None,
+                            untracked_env: None,
                             input: None,
                         }
                     }),

crates/vite_task_bin/tests/e2e_snapshots/fixtures/cache-miss-reasons/snapshots.toml

@@ -22,20 +22,20 @@ steps = [
 ]
 
 [[e2e]]
-name = "pass-through env added"
+name = "untracked env added"
 steps = [
   "vp run test # cache miss",
-  "json-edit vite-task.json \"_.tasks.test.passThroughEnvs = ['MY_PASSTHROUGH']\" # add pass-through env",
-  "vp run test # cache miss: pass-through env added",
+  "json-edit vite-task.json \"_.tasks.test.untrackedEnv = ['MY_UNTRACKED']\" # add untracked env",
+  "vp run test # cache miss: untracked env added",
 ]
 
 [[e2e]]
-name = "pass-through env removed"
+name = "untracked env removed"
 steps = [
-  "json-edit vite-task.json \"_.tasks.test.passThroughEnvs = ['MY_PASSTHROUGH']\" # setup",
+  "json-edit vite-task.json \"_.tasks.test.untrackedEnv = ['MY_UNTRACKED']\" # setup",
   "vp run test # cache miss",
-  "json-edit vite-task.json \"delete _.tasks.test.passThroughEnvs\" # remove pass-through env",
-  "vp run test # cache miss: pass-through env removed",
+  "json-edit vite-task.json \"delete _.tasks.test.untrackedEnv\" # remove untracked env",
+  "vp run test # cache miss: untracked env removed",
 ]
 
 [[e2e]]

crates/vite_task_bin/tests/e2e_snapshots/fixtures/cache-miss-reasons/snapshots/pass-through env added.snap

@@ -0,0 +1,12 @@
+---
+source: crates/vite_task_bin/tests/e2e_snapshots/main.rs
+expression: e2e_outputs
+---
+> vp run test # cache miss
+$ print-file test.txt
+initial content
+> json-edit vite-task.json "_.tasks.test.untrackedEnv = ['MY_UNTRACKED']" # add untracked env
+
+> vp run test # cache miss: untracked env added
+$ print-file test.txt ✗ cache miss: untracked env config changed, executing
+initial content