feat: workspace root microsyntax (#10094)

anthonyshew · chris-olszewski · web-flow · commit 79dfe99090ed · 2025-03-14T12:38:39.000-04:00
### Description Microsyntax for file globbing from the workspace root. Our file globs are anchored to packages, but there are use cases where anchoring at the root is more preferable. Adds `$TURBO_ROOT$` which can be used in task `inputs` and `outputs`. It can only be used at the start of an inclusion/exclusion so `../$TURBO_ROOT$/config.txt` isn't valid usage. We achieve this by swapping out `$TURBO_ROOT$` as we convert a raw task definition to a usable one. This allows us to not handle this at any later steps since all inputs/outpus are expected to be relative to the package directory. ### Testing Instructions Added unit tests for: - Replacing of `$TURBO_ROOT$` with the relative path to the repo root - Calculation of the relative path to repo root for packages ``` [0 olszewski@macbookpro] /tmp/watch-time $ bat turbo.json ───────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │ File: turbo.json ───────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 1 │ { 2 │ "$schema": "https://turbo.build/schema.json", 3 │ "ui": "tui", 4 │ "tasks": { 5 │ "build": { 6 │ "dependsOn": ["^build"], 7 ~ │ "inputs": ["$TURBO_DEFAULT$", ".env*", "$TURBO_ROOT$/my-configs/*"], 8 │ "outputs": [".next/**", "!.next/cache/**"] 9 │ }, 10 │ "lint": { 11 │ "dependsOn": ["^lint"] 12 │ }, 13 │ "check-types": { 14 │ "dependsOn": ["^check-types"] 15 │ }, 16 │ "dev": { 17 │ "cache": false, 18 │ "persistent": true 19 │ } 20 │ } 21 │ } [0 olszewski@macbookpro] /tmp/watch-time $ turbo_dev --skip-infer build --output-logs=hash-only turbo 2.4.5-canary.2 • Packages in scope: @repo/eslint-config, @repo/typescript-config, @repo/ui, docs, web • Running build in 5 packages • Remote caching disabled web#build > cache hit, suppressing logs cf5b7818b9c2c383 docs#build > cache hit, suppressing logs 9306af3d3750177a Tasks: 2 successful, 2 total Cached: 2 cached, 2 total Time: 110ms >>> FULL TURBO [0 olszewski@macbookpro] /tmp/watch-time $ echo 'a change' > my-configs/config.txt [0 olszewski@macbookpro] /tmp/watch-time $ turbo_dev --skip-infer build --output-logs=hash-only turbo 2.4.5-canary.2 • Packages in scope: @repo/eslint-config, @repo/typescript-config, @repo/ui, docs, web • Running build in 5 packages • Remote caching disabled web#build > cache miss, executing 0acfce06b3b2069d docs#build > cache miss, executing cfb4227df7dfd1fc Tasks: 2 successful, 2 total Cached: 0 cached, 2 total Time: 7.97s [0 olszewski@macbookpro] /tmp/watch-time $ vim turbo.json [0 olszewski@macbookpro] /tmp/watch-time $ turbo_dev --skip-infer build --output-logs=hash-only turbo 2.4.5-canary.2 × Cannot use '$TURBO_ROOT$' anywhere besides start of string. ╭─[turbo.json:7:46] 6 │ "dependsOn": ["^build"], 7 │ "inputs": ["$TURBO_DEFAULT$", ".env*", "../$TURBO_ROOT$/my-configs/*"], · ───────────────┬────────────── · ╰── must be at start 8 │ "outputs": [".next/**", "!.next/cache/**"] ╰──── ``` --------- Co-authored-by: Chris Olszewski <chris.olszewski@vercel.com>
diff --git a/crates/turborepo-lib/src/config/mod.rs b/crates/turborepo-lib/src/config/mod.rs
@@ -204,6 +204,20 @@ pub enum Error {
     },
     #[error("Cannot load turbo.json for {0} in single package mode.")]
     InvalidTurboJsonLoad(PackageName),
+    #[error("\"$TURBO_ROOT$\" must be used at the start of glob.")]
+    InvalidTurboRootUse {
+        #[label("\"$TURBO_ROOT$\" must be used at the start of glob.")]
+        span: Option<SourceSpan>,
+        #[source_code]
+        text: NamedSource<String>,
+    },
+    #[error("\"$TURBO_ROOT$\" must be followed by a '/'.")]
+    InvalidTurboRootNeedsSlash {
+        #[label("\"$TURBO_ROOT$\" must be followed by a '/'.")]
+        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,9 @@ pub use loader::TurboJsonLoader;
 
 use crate::{boundaries::BoundariesConfig, config::UnnecessaryPackageTaskSyntaxError};
 
+const TURBO_ROOT: &str = "$TURBO_ROOT$";
+const TURBO_ROOT_SLASH: &str = "$TURBO_ROOT$/";
+
 #[derive(Serialize, Deserialize, Debug, Default, PartialEq, Clone, Deserializable)]
 #[serde(rename_all = "camelCase")]
 pub struct SpacesJson {
@@ -343,10 +346,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 +577,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 +605,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 +636,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 +772,82 @@ 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> {
+    let turbo_root_index = input.find(TURBO_ROOT);
+    if let Some(index) = turbo_root_index {
+        if !input.as_inner()[index..].starts_with(TURBO_ROOT_SLASH) {
+            let (span, text) = input.span_and_text("turbo.json");
+            return Err(Error::InvalidTurboRootNeedsSlash { span, text });
+        }
+    }
+    match turbo_root_index {
+        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 +859,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 +1026,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 +1063,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 +1287,25 @@ 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("\"$TURBO_ROOT$\" must be used at the start of glob.") ; "invalid token")]
+    #[test_case("$TURBO_ROOT$config.txt", Err("\"$TURBO_ROOT$\" must be followed by a '/'.") ; "trailing slash")]
+    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()));
+    }
 }
diff --git a/crates/turborepo-unescape/src/lib.rs b/crates/turborepo-unescape/src/lib.rs
@@ -1,4 +1,7 @@
-use std::{fmt, fmt::Display, ops::Deref};
+use std::{
+    fmt::{self, Display},
+    ops::{Deref, DerefMut},
+};
 
 use biome_deserialize::{Deserializable, DeserializableValue, DeserializationDiagnostic};
 
@@ -21,12 +24,19 @@ impl AsRef<str> for UnescapedString {
 }
 
 impl Deref for UnescapedString {
-    type Target = str;
+    type Target = String;
 
     fn deref(&self) -> &Self::Target {
         &self.0
     }
 }
+
+impl DerefMut for UnescapedString {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}
+
 fn unescape_str(s: String) -> Result<String, serde_json::Error> {
     let wrapped_s = format!("\"{}\"", s);
 
diff --git a/docs/site/content/repo-docs/reference/configuration.mdx b/docs/site/content/repo-docs/reference/configuration.mdx
