vercel · chris-olszewski · Aug 21, 2025 · Jul 30, 2025 · Jul 30, 2025 · Aug 12, 2025
@@ -255,6 +255,8 @@ impl ResolvedConfigurationOptions for EnvVars {
             root_turbo_json_path,
             log_order,
             sso_login_callback_port,
+            // Do not allow future flags to be set by env var
+            future_flags: None,
         };
 
         Ok(output)

@@ -23,8 +23,11 @@ use turborepo_cache::CacheConfig;
 use turborepo_errors::TURBO_SITE;
 use turborepo_repository::package_graph::PackageName;
 
-use crate::cli::{EnvMode, LogOrder};
 pub use crate::turbo_json::{RawTurboJson, UIMode};
+use crate::{
+    cli::{EnvMode, LogOrder},
+    turbo_json::FutureFlags,
+};
 
 pub const CONFIG_FILE: &str = "turbo.json";
 pub const CONFIG_FILE_JSONC: &str = "turbo.jsonc";
@@ -312,6 +315,8 @@ pub struct ConfigurationOptions {
     pub(crate) concurrency: Option<String>,
     pub(crate) no_update_notifier: Option<bool>,
     pub(crate) sso_login_callback_port: Option<u16>,
+    #[serde(skip)]
+    future_flags: Option<FutureFlags>,
 }
 
 #[derive(Default)]
@@ -471,6 +476,10 @@ impl ConfigurationOptions {
     pub fn sso_login_callback_port(&self) -> Option<u16> {
         self.sso_login_callback_port
     }
+
+    pub fn future_flags(&self) -> FutureFlags {
+        self.future_flags.unwrap_or_default()
+    }
 }
 
 // Maps Some("") to None to emulate how Go handles empty strings

@@ -78,6 +78,7 @@ impl<'a> TurboJsonReader<'a> {
         opts.env_mode = turbo_json.env_mode.map(|mode| *mode.as_inner());
         opts.cache_dir = cache_dir;
         opts.concurrency = turbo_json.concurrency.map(|c| c.as_inner().clone());
+        opts.future_flags = turbo_json.future_flags.map(|f| *f.as_inner());
         Ok(opts)
     }
 }

@@ -15,7 +15,7 @@ use crate::{
     task_graph::TaskDefinition,
     turbo_json::{
         validate_extends, validate_no_package_task_syntax, validate_with_has_no_topo,
-        RawTaskDefinition, TurboJsonLoader,
+        ProcessedTaskDefinition, TurboJsonLoader,
     },
 };
 
@@ -564,14 +564,12 @@ impl<'a> EngineBuilder<'a> {
         task_id: &Spanned<TaskId>,
         task_name: &TaskName,
     ) -> Result<TaskDefinition, Error> {
-        let raw_task_definition = RawTaskDefinition::from_iter(self.task_definition_chain(
-            turbo_json_loader,
-            task_id,
-            task_name,
-        )?);
+        let processed_task_definition = ProcessedTaskDefinition::from_iter(
+            self.task_definition_chain(turbo_json_loader, task_id, task_name)?,
+        );
         let path_to_root = self.path_to_root(task_id.as_inner())?;
-        Ok(TaskDefinition::from_raw(
-            raw_task_definition,
+        Ok(TaskDefinition::from_processed(
+            processed_task_definition,
             &path_to_root,
         )?)
     }
@@ -581,13 +579,13 @@ impl<'a> EngineBuilder<'a> {
         turbo_json_loader: &TurboJsonLoader,
         task_id: &Spanned<TaskId>,
         task_name: &TaskName,
-    ) -> Result<Vec<RawTaskDefinition>, Error> {
+    ) -> Result<Vec<ProcessedTaskDefinition>, Error> {
         let mut task_definitions = Vec::new();
 
         let root_turbo_json = turbo_json_loader.load(&PackageName::Root)?;
         Error::from_validation(root_turbo_json.validate(&[validate_with_has_no_topo]))?;
 
-        if let Some(root_definition) = root_turbo_json.task(task_id, task_name) {
+        if let Some(root_definition) = root_turbo_json.task(task_id, task_name)? {
             task_definitions.push(root_definition)
         }
 
@@ -616,8 +614,8 @@ impl<'a> EngineBuilder<'a> {
                         validate_with_has_no_topo,
                     ]))?;
 
-                    if let Some(workspace_def) = workspace_json.tasks.get(task_name) {
-                        task_definitions.push(workspace_def.value.clone());
+                    if let Some(workspace_def) = workspace_json.task(task_id, task_name)? {
+                        task_definitions.push(workspace_def);
                     }
                 }
                 Err(config::Error::NoTurboJSON) => (),

@@ -14,7 +14,7 @@ use crate::{
         OutputLogsMode, RunArgs,
     },
     config::{ConfigurationOptions, CONFIG_FILE},
-    turbo_json::UIMode,
+    turbo_json::{FutureFlags, UIMode},
     Args,
 };
 
@@ -77,6 +77,7 @@ pub struct Opts {
     pub runcache_opts: RunCacheOpts,
     pub scope_opts: ScopeOpts,
     pub tui_opts: TuiOpts,
+    pub future_flags: FutureFlags,
 }
 
 impl Opts {
@@ -180,6 +181,7 @@ impl Opts {
         let api_client_opts = APIClientOpts::from(inputs);
         let repo_opts = RepoOpts::from(inputs);
         let tui_opts = TuiOpts::from(inputs);
+        let future_flags = config.future_flags();
 
         Ok(Self {
             repo_opts,
@@ -189,6 +191,7 @@ impl Opts {
             runcache_opts,
             api_client_opts,
             tui_opts,
+            future_flags,
         })
     }
 }
@@ -747,6 +750,7 @@ mod test {
             cache_opts,
             runcache_opts,
             tui_opts,
+            future_flags: Default::default(),
         };
         let synthesized = opts.synthesize_command();
         assert_eq!(synthesized, expected);

@@ -25,7 +25,7 @@ use turborepo_scm::GitHashes;
 
 use crate::{
     config::{resolve_turbo_config_path, CONFIG_FILE, CONFIG_FILE_JSONC},
-    turbo_json::{TurboJson, TurboJsonLoader},
+    turbo_json::{TurboJson, TurboJsonLoader, TurboJsonReader},
 };
 
 #[derive(Clone)]
@@ -232,7 +232,7 @@ impl Subscriber {
         };
 
         let root_turbo_json = TurboJsonLoader::workspace(
-            self.repo_root.clone(),
+            TurboJsonReader::new(self.repo_root.clone()),
             config_path,
             pkg_dep_graph.packages(),
         )

@@ -49,7 +49,7 @@ use crate::{
     opts::Opts,
     run::{scope, task_access::TaskAccess, Error, Run, RunCache},
     shim::TurboState,
-    turbo_json::{TurboJson, TurboJsonLoader, UIMode},
+    turbo_json::{TurboJson, TurboJsonLoader, TurboJsonReader, UIMode},
     DaemonConnector,
 };
 
@@ -408,16 +408,19 @@ impl RunBuilder {
         task_access.restore_config().await;
 
         let root_turbo_json_path = self.opts.repo_opts.root_turbo_json_path.clone();
+        let future_flags = self.opts.future_flags;
+
+        let reader = TurboJsonReader::new(self.repo_root.clone()).with_future_flags(future_flags);
 
         let turbo_json_loader = if task_access.is_enabled() {
             TurboJsonLoader::task_access(
-                self.repo_root.clone(),
+                reader,
                 root_turbo_json_path.clone(),
                 root_package_json.clone(),
             )
         } else if is_single_package {
             TurboJsonLoader::single_package(
-                self.repo_root.clone(),
+                reader,
                 root_turbo_json_path.clone(),
                 root_package_json.clone(),
             )
@@ -426,20 +429,20 @@ impl RunBuilder {
         (self.opts.repo_opts.allow_no_turbo_json || micro_frontend_configs.is_some())
         {
             TurboJsonLoader::workspace_no_turbo_json(
-                self.repo_root.clone(),
+                reader,
                 pkg_dep_graph.packages(),
                 micro_frontend_configs.clone(),
             )
         } else if let Some(micro_frontends) = &micro_frontend_configs {
             TurboJsonLoader::workspace_with_microfrontends(
-                self.repo_root.clone(),
+                reader,
                 root_turbo_json_path.clone(),
                 pkg_dep_graph.packages(),
                 micro_frontends.clone(),
             )
         } else {
             TurboJsonLoader::workspace(
-                self.repo_root.clone(),
+                reader,
                 root_turbo_json_path.clone(),
                 pkg_dep_graph.packages(),
             )

@@ -9,9 +9,10 @@ The loading and resolving of task definitions is driven during task graph constr
 The configuration and task loading process follows this high-level flow:
 
 1. **Configuration Resolution**: Collect and merge configuration from multiple sources
-2. **TurboJson Loading**: Resolve `turbo.json` files, these are usually files on disk, but can be synthesized
-3. **Task Definition Resolution**: Convert raw task definitions into validated structures. `extends` is handled in this step
-4. **Task Graph Construction**: Build the executable task graph from resolved definitions
+2. **TurboJson Loading**: Parse `turbo.json` files into raw structures
+3. **Task Processing**: Convert raw definitions to processed intermediate representation with DSL token handling
+4. **Task Definition Resolution**: Transform processed definitions into final validated structures
+5. **Task Graph Construction**: Build the executable task graph from resolved definitions
 
 ## Phase 1: Configuration Resolution
 
@@ -39,30 +40,66 @@ Configuration is collected from multiple sources with the following priority (hi
 
 - **`TurboJsonLoader`** (`crates/turborepo-lib/src/turbo_json/loader.rs`): Loads and resolves turbo.json files
 - **`RawTurboJson`**: Raw deserialized structure from JSON files
-- **`TurboJson`**: Resolved and validated structure, all DSL magic strings have been handled
+- **`TurboJson`**: Validated structure containing raw task definitions
 
 ### Process
 
 1. **File Discovery**: Locate `turbo.json` or `turbo.jsonc` files
 2. **Parsing**: Deserialize JSON into `RawTurboJson` structures
-3. **Validation**: Convert to `TurboJson` with validation rules
+3. **Basic Validation**: Convert to `TurboJson` with structural validation
 4. **Workspace Resolution**: Apply workspace-specific overrides
 
-## Phase 3: Task Definition Resolution
+## Phase 3: Processed Task Definition (Intermediate Representation)
+
+### Key Components
+
+- **`ProcessedTaskDefinition`** (`crates/turborepo-lib/src/turbo_json/processed.rs`): Intermediate representation with DSL token processing
+- **`ProcessedGlob`**: Parsed glob patterns with separated components (base pattern, negation flag, turbo_root flag)
+- **`ProcessedInputs`/`ProcessedOutputs`**: Collections of processed globs with resolution methods
+
+### Processing Steps
+
+1. **DSL Token Detection**: Identify and separate `$TURBO_ROOT$` and `!` prefixes from glob patterns
+2. **Early Validation**: Single-field validations at parse time with span information:
+   - Absolute paths in inputs/outputs
+   - Invalid `$TURBO_ROOT$` usage
+   - Environment variable prefixes (`$` not allowed)
+   - Dependency prefixes (`$` not allowed in `dependsOn`)
+   - Topological references (`^` not allowed in `with`)
+3. **Prefix Stripping**: Store clean glob patterns without DSL prefixes
+4. **Component Separation**: Track negation and turbo_root requirements as separate boolean flags
+
+## Phase 4: Task Definition Resolution
 
 ### Key Components
 
 - **`RawTaskDefinition`**: Raw task configuration from JSON
-- **`TaskDefinition`**: Validated and processed task configuration
+- **`ProcessedTaskDefinition`**: Intermediate representation with parsed DSL tokens
+- **`TaskDefinition`**: Final validated and resolved task configuration
 - **`TaskId`** and **`TaskName`** (from `turborepo-task-id` crate): Task identification types
 
 ### Transformation Process
 
-Raw task definitions undergo several transformations:
+The resolution now follows a three-stage pipeline:
+
+1. **Raw → Processed** (`ProcessedTaskDefinition::from_raw`):
+
+   - Parse glob patterns and extract DSL tokens
+   - Validate single-field constraints with span information:
+     - Absolute paths in inputs/outputs (`ProcessedGlob::from_spanned_*`)
+     - Invalid environment variable prefixes (`ProcessedEnv::new`, `ProcessedPassThroughEnv::new`)
+     - Invalid dependency syntax (`ProcessedDependsOn::new`)
+     - Invalid sibling task references (`ProcessedWith::new`)
+   - Strip prefixes and store components separately
+
+2. **Processed → Resolved** (`TaskDefinition::from_processed`):
+
+   - Apply `$TURBO_ROOT$` token replacement using `resolve()` methods
+   - Parse `dependsOn` into topological and task dependencies
+   - Transform environment variables into sorted lists
+   - Transform outputs into inclusion/exclusion patterns
+   - Validate multi-field constraints:
+     - Interactive tasks cannot be cached (requires `cache` and `interactive` fields)
+     - Interruptible tasks must be persistent (requires `interruptible` and `persistent` fields)
 
-1. **Path Resolution**: Convert relative paths and handle `$TURBO_ROOT$` tokens
-2. **Dependency Parsing**: Parse `dependsOn` into topological and task dependencies
-3. **Environment Variable Collection**: Extract `env` and `passThroughEnv` variables
-4. **Output Processing**: Handle inclusion/exclusion patterns in outputs
-5. **Inheritance**: Handle merging multiple `RawTaskDefinition`s into a single usable task definition
-6. **Validation**: Ensure configuration consistency (e.g., interactive tasks can't be cached)
+3. **Inheritance**: The `extend` module handles merging multiple `ProcessedTaskDefinition`s before final resolution