feat(turbo_json): $TURBO_ROOT$

anthonyshew · chris-olszewski · commit 320289170e27 · 2025-03-12T19:17:10.000-04:00
diff --git a/crates/turborepo-lib/src/config/mod.rs b/crates/turborepo-lib/src/config/mod.rs
@@ -204,6 +204,13 @@ pub enum Error {
     },
     #[error("Cannot load turbo.json for {0} in single package mode.")]
     InvalidTurboJsonLoad(PackageName),
+    #[error("Cannot use '$TURBO_ROOT$' anywhere besides start of string.")]
+    InvalidTurboRootUse {
+        #[label("must be at start")]
+        span: Option<SourceSpan>,
+        #[source_code]
+        text: NamedSource<String>,
+    },
 }
 
 const DEFAULT_API_URL: &str = "https://vercel.com/api";
diff --git a/crates/turborepo-lib/src/engine/builder.rs b/crates/turborepo-lib/src/engine/builder.rs
@@ -3,7 +3,7 @@ use std::collections::{HashMap, HashSet, VecDeque};
 use convert_case::{Case, Casing};
 use itertools::Itertools;
 use miette::{Diagnostic, NamedSource, SourceSpan};
-use turbopath::AbsoluteSystemPath;
+use turbopath::{AbsoluteSystemPath, AnchoredSystemPathBuf, RelativeUnixPathBuf};
 use turborepo_errors::{Spanned, TURBO_SITE};
 use turborepo_graph_utils as graph;
 use turborepo_repository::package_graph::{PackageGraph, PackageName, PackageNode, ROOT_PKG_NAME};
@@ -568,8 +568,11 @@ impl<'a> EngineBuilder<'a> {
             task_id,
             task_name,
         )?);
-
-        Ok(TaskDefinition::try_from(raw_task_definition)?)
+        let path_to_root = self.path_to_root(task_id.as_inner())?;
+        Ok(TaskDefinition::from_raw(
+            raw_task_definition,
+            &path_to_root,
+        )?)
     }
 
     fn task_definition_chain(
@@ -638,6 +641,22 @@ impl<'a> EngineBuilder<'a> {
 
         Ok(task_definitions)
     }
+
+    // Returns that path from a task's package directory to the repo root
+    fn path_to_root(&self, task_id: &TaskId) -> Result<RelativeUnixPathBuf, Error> {
+        let package_name = PackageName::from(task_id.package());
+        let pkg_path = self
+            .package_graph
+            .package_dir(&package_name)
+            .ok_or_else(|| Error::MissingPackageJson {
+                workspace: package_name,
+            })?;
+        Ok(AnchoredSystemPathBuf::relative_path_between(
+            &self.repo_root.resolve(pkg_path),
+            self.repo_root,
+        )
+        .to_unix())
+    }
 }
 
 impl Error {
@@ -1595,4 +1614,45 @@ mod test {
             "only the root task node should be present"
         );
     }
+
+    #[test]
+    fn test_path_to_root() {
+        let repo_root_dir = TempDir::with_prefix("repo").unwrap();
+        let repo_root = AbsoluteSystemPathBuf::new(repo_root_dir.path().to_str().unwrap()).unwrap();
+        let package_graph = mock_package_graph(
+            &repo_root,
+            package_jsons! {
+                repo_root,
+                "app1" => ["libA"],
+                "libA" => []
+            },
+        );
+        let turbo_jsons = vec![(
+            PackageName::Root,
+            turbo_json(json!({
+                "tasks": {
+                    "build": { "dependsOn": ["^build"] },
+                }
+            })),
+        )]
+        .into_iter()
+        .collect();
+        let loader = TurboJsonLoader::noop(turbo_jsons);
+        let engine = EngineBuilder::new(&repo_root, &package_graph, &loader, false);
+        assert_eq!(
+            engine
+                .path_to_root(&TaskId::new("//", "build"))
+                .unwrap()
+                .as_str(),
+            "."
+        );
+        // libA is located at packages/libA
+        assert_eq!(
+            engine
+                .path_to_root(&TaskId::new("libA", "build"))
+                .unwrap()
+                .as_str(),
+            "../.."
+        );
+    }
 }
diff --git a/crates/turborepo-lib/src/turbo_json/loader.rs b/crates/turborepo-lib/src/turbo_json/loader.rs
@@ -434,6 +434,7 @@ mod test {
     use insta::assert_snapshot;
     use tempfile::tempdir;
     use test_case::test_case;
+    use turbopath::RelativeUnixPath;
     use turborepo_unescape::UnescapedString;
 
     use super::*;
@@ -616,7 +617,7 @@ mod test {
 
         assert_eq!(
             expected_root_build,
-            TaskDefinition::try_from(root_build.clone())?
+            TaskDefinition::from_raw(root_build.clone(), RelativeUnixPath::new(".").unwrap())?
         );
 
         Ok(())
diff --git a/crates/turborepo-lib/src/turbo_json/mod.rs b/crates/turborepo-lib/src/turbo_json/mod.rs
@@ -11,7 +11,7 @@ use clap::ValueEnum;
 use miette::{NamedSource, SourceSpan};
 use serde::{Deserialize, Serialize};
 use struct_iterable::Iterable;
-use turbopath::AbsoluteSystemPath;
+use turbopath::{AbsoluteSystemPath, RelativeUnixPath};
 use turborepo_errors::Spanned;
 use turborepo_repository::package_graph::ROOT_PKG_NAME;
 use turborepo_unescape::UnescapedString;
@@ -33,6 +33,8 @@ pub use loader::TurboJsonLoader;
 
 use crate::{boundaries::BoundariesConfig, config::UnnecessaryPackageTaskSyntaxError};
 
+const TURBO_ROOT: &str = "$TURBO_ROOT$";
+
 #[derive(Serialize, Deserialize, Debug, Default, PartialEq, Clone, Deserializable)]
 #[serde(rename_all = "camelCase")]
 pub struct SpacesJson {
@@ -343,10 +345,12 @@ impl TryFrom<Vec<Spanned<UnescapedString>>> for TaskOutputs {
     }
 }
 
-impl TryFrom<RawTaskDefinition> for TaskDefinition {
-    type Error = Error;
-
-    fn try_from(raw_task: RawTaskDefinition) -> Result<Self, Error> {
+impl TaskDefinition {
+    pub fn from_raw(
+        mut raw_task: RawTaskDefinition,
+        path_to_repo_root: &RelativeUnixPath,
+    ) -> Result<Self, Error> {
+        replace_turbo_root_token(&mut raw_task, path_to_repo_root)?;
         let outputs = raw_task.outputs.unwrap_or_default().try_into()?;
 
         let cache = raw_task.cache.is_none_or(|c| c.into_inner());
@@ -572,6 +576,8 @@ impl TryFrom<RawTurboJson> for TurboJson {
             }
         }
 
+        let tasks = raw_turbo.tasks.clone().unwrap_or_default();
+
         Ok(TurboJson {
             text: raw_turbo.span.text,
             path: raw_turbo.span.path,
@@ -598,7 +604,7 @@ impl TryFrom<RawTurboJson> for TurboJson {
 
                 global_deps
             },
-            tasks: raw_turbo.tasks.unwrap_or_default(),
+            tasks,
             // copy these over, we don't need any changes here.
             extends: raw_turbo
                 .extends
@@ -629,7 +635,7 @@ impl TurboJson {
         path: &AbsoluteSystemPath,
     ) -> Result<TurboJson, Error> {
         let raw_turbo_json = RawTurboJson::read(repo_root, path)?;
-        raw_turbo_json.try_into()
+        TurboJson::try_from(raw_turbo_json)
     }
 
     pub fn task(&self, task_id: &TaskId, task_name: &TaskName) -> Option<RawTaskDefinition> {
@@ -765,17 +771,75 @@ fn gather_env_vars(
     Ok(())
 }
 
+// Takes an input/output glob that might start with TURBO_ROOT_PREFIX
+// and swap it with the relative path to the turbo root.
+fn replace_turbo_root_token_in_string(
+    input: &mut Spanned<UnescapedString>,
+    path_to_repo_root: &RelativeUnixPath,
+) -> Result<(), Error> {
+    match input.find(TURBO_ROOT) {
+        Some(0) => {
+            // Replace
+            input
+                .as_inner_mut()
+                .replace_range(..TURBO_ROOT.len(), path_to_repo_root.as_str());
+            Ok(())
+        }
+        // Handle negations
+        Some(1) if input.starts_with('!') => {
+            input
+                .as_inner_mut()
+                .replace_range(1..TURBO_ROOT.len() + 1, path_to_repo_root.as_str());
+            Ok(())
+        }
+        // We do not allow for TURBO_ROOT to be used in the middle of a glob
+        Some(_) => {
+            let (span, text) = input.span_and_text("turbo.json");
+            Err(Error::InvalidTurboRootUse { span, text })
+        }
+        None => Ok(()),
+    }
+}
+
+fn replace_turbo_root_token(
+    task_definition: &mut RawTaskDefinition,
+    path_to_repo_root: &RelativeUnixPath,
+) -> Result<(), Error> {
+    for input in task_definition
+        .inputs
+        .iter_mut()
+        .flat_map(|inputs| inputs.iter_mut())
+    {
+        replace_turbo_root_token_in_string(input, path_to_repo_root)?;
+    }
+
+    for output in task_definition
+        .outputs
+        .iter_mut()
+        .flat_map(|outputs| outputs.iter_mut())
+    {
+        replace_turbo_root_token_in_string(output, path_to_repo_root)?;
+    }
+
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
+    use std::sync::Arc;
+
     use anyhow::Result;
     use biome_deserialize::json::deserialize_from_json_str;
     use biome_json_parser::JsonParserOptions;
     use pretty_assertions::assert_eq;
     use serde_json::json;
     use test_case::test_case;
+    use turbopath::RelativeUnixPath;
     use turborepo_unescape::UnescapedString;
 
-    use super::{RawTurboJson, SpacesJson, Spanned, TurboJson, UIMode};
+    use super::{
+        replace_turbo_root_token_in_string, RawTurboJson, SpacesJson, Spanned, TurboJson, UIMode,
+    };
     use crate::{
         boundaries::BoundariesConfig,
         cli::OutputLogsMode,
@@ -787,7 +851,7 @@ mod tests {
     #[test_case("{}", "empty boundaries")]
     #[test_case(r#"{"tags": {} }"#, "empty tags")]
     #[test_case(
-        r#"{"tags": { "my-tag": { "dependencies": { "allow": ["my-package"] } } } }"#,
+        r#"{"tags": { "my-tag": { "dependencies": { "allow": ["my-package"] } } }"#,
         "tags and dependencies"
     )]
     #[test_case(
@@ -954,6 +1018,29 @@ mod tests {
         }
       ; "full (windows)"
     )]
+    #[test_case(
+        r#"{
+            "inputs": ["$TURBO_ROOT$/config.txt"],
+            "outputs": ["$TURBO_ROOT$/coverage/**", "!$TURBO_ROOT$/coverage/index.html"]
+        }"#,
+        RawTaskDefinition {
+            inputs: Some(vec![Spanned::new(UnescapedString::from("$TURBO_ROOT$/config.txt")).with_range(25..50)]),
+            outputs: Some(vec![
+                Spanned::new(UnescapedString::from("$TURBO_ROOT$/coverage/**")).with_range(77..103),
+                Spanned::new(UnescapedString::from("!$TURBO_ROOT$/coverage/index.html")).with_range(105..140),
+            ]),
+            ..RawTaskDefinition::default()
+        },
+        TaskDefinition {
+            inputs: vec!["../../config.txt".to_owned()],
+            outputs: TaskOutputs {
+                inclusions: vec!["../../coverage/**".to_owned()],
+                exclusions: vec!["../../coverage/index.html".to_owned()],
+            },
+            ..TaskDefinition::default()
+        }
+    ; "turbo root"
+    )]
     fn test_deserialize_task_definition(
         task_definition_content: &str,
         expected_raw_task_definition: RawTaskDefinition,
@@ -968,7 +1055,8 @@ mod tests {
             deserialized_result.into_deserialized().unwrap();
         assert_eq!(raw_task_definition, expected_raw_task_definition);
 
-        let task_definition: TaskDefinition = raw_task_definition.try_into()?;
+        let task_definition =
+            TaskDefinition::from_raw(raw_task_definition, RelativeUnixPath::new("../..").unwrap())?;
         assert_eq!(task_definition, expected_task_definition);
 
         Ok(())
@@ -1191,4 +1279,24 @@ mod tests {
             &[Spanned::new(UnescapedString::from("api#server"))]
         );
     }
+
+    #[test_case("index.ts", Ok("index.ts") ; "no token")]
+    #[test_case("$TURBO_ROOT$/config.txt", Ok("../../config.txt") ; "valid token")]
+    #[test_case("!$TURBO_ROOT$/README.md", Ok("!../../README.md") ; "negation")]
+    #[test_case("../$TURBO_ROOT$/config.txt", Err("Cannot use '$TURBO_ROOT$' anywhere besides start of string.") ; "invalid token")]
+    fn test_replace_turbo_root(input: &'static str, expected: Result<&str, &str>) {
+        let mut spanned_string = Spanned::new(UnescapedString::from(input))
+            .with_path(Arc::from("turbo.json"))
+            .with_text(format!("\"{input}\""))
+            .with_range(1..(input.len()));
+        let result = replace_turbo_root_token_in_string(
+            &mut spanned_string,
+            RelativeUnixPath::new("../..").unwrap(),
+        );
+        let actual = match result {
+            Ok(()) => Ok(spanned_string.as_inner().as_ref()),
+            Err(e) => Err(e.to_string()),
+        };
+        assert_eq!(actual, expected.map_err(|s| s.to_owned()));
+    }
 }
