fix: Treat npm: alias dependencies as external, not workspace references (#12061)

## Summary

Fixes #8989

- When a dependency uses the `npm:` alias syntax (e.g. `"buffer":
"npm:buffer@6.0.3"`), turborepo incorrectly resolved it to a workspace
of the same name instead of the npm registry package. The
`npm:<pkg>@<version>` format explicitly targets the npm registry and
should never match a workspace.

## Root cause

`DependencyVersion::new("npm:buffer@6.0.3")` splits into
`protocol="npm"` and `version="buffer@6.0.3"`. Since `npm` is
special-cased to not be treated as external (for transparent workspace
support), the code falls through to semver comparison. `"buffer@6.0.3"`
fails to parse as a semver range, and the backwards-compatibility
fallback treats parse failures as internal matches.

## Fix

Added `is_npm_alias()` to detect the `npm:<pkg>@<version>` alias format
(including scoped packages like `npm:@scope/pkg@^1.0.0`). Aliased npm
dependencies are always treated as external since they explicitly target
the npm registry. This is distinct from plain `npm:^1.0.0` ranges which
still participate in transparent workspace resolution.

## Testing

To understand the fix, the `test_is_npm_alias` and
`test_matches_workspace_package` ("handles npm alias with matching
workspace name") test cases in `dep_splitter.rs` are the most relevant.
A berry lockfile test (`test_npm_alias_does_not_resolve_to_workspace`)
verifies the lockfile resolution and pruning paths. A `berry-npm-alias`
fixture was added to `lockfile-tests/fixtures/` reproducing the exact
scenario from the issue.

Author: anthonyshew

crates/turborepo-lockfiles/src/berry/mod.rs

@@ -696,6 +696,87 @@ mod test {
         }
     }
 
+    #[test]
+    fn test_npm_alias_does_not_resolve_to_workspace() {
+        // Regression test for https://github.com/vercel/turborepo/issues/8989
+        // When a dependency uses `npm:buffer@6.0.3`, it should resolve to the
+        // npm package, not the workspace with the same name.
+        let yaml = r#"__metadata:
+  version: 8
+  cacheKey: 10c0
+
+"a@workspace:packages/a":
+  version: 0.0.0-use.local
+  resolution: "a@workspace:packages/a"
+  dependencies:
+    buffer: "npm:buffer@6.0.3"
+  languageName: unknown
+  linkType: soft
+
+"base64-js@npm:^1.3.1":
+  version: 1.5.1
+  resolution: "base64-js@npm:1.5.1"
+  checksum: 10c0-abc123
+  languageName: node
+  linkType: hard
+
+"root@workspace:.":
+  version: 0.0.0-use.local
+  resolution: "root@workspace:."
+  languageName: unknown
+  linkType: soft
+
+"buffer@npm:buffer@6.0.3":
+  version: 6.0.3
+  resolution: "buffer@npm:6.0.3"
+  dependencies:
+    base64-js: "npm:^1.3.1"
+    ieee754: "npm:^1.2.1"
+  checksum: 10c0-def456
+  languageName: node
+  linkType: hard
+
+"buffer@workspace:packages/buffer":
+  version: 0.0.0-use.local
+  resolution: "buffer@workspace:packages/buffer"
+  languageName: unknown
+  linkType: soft
+
+"ieee754@npm:^1.2.1":
+  version: 1.2.1
+  resolution: "ieee754@npm:1.2.1"
+  checksum: 10c0-ghi789
+  languageName: node
+  linkType: hard
+"#;
+
+        let data = LockfileData::from_bytes(yaml.as_bytes()).unwrap();
+        let lockfile = BerryLockfile::new(data, None).unwrap();
+
+        // Resolving "buffer" with version "npm:buffer@6.0.3" from workspace "a"
+        // should return the npm package, not the workspace.
+        let resolved = lockfile
+            .resolve_package("packages/a", "buffer", "npm:buffer@6.0.3")
+            .unwrap();
+        assert!(resolved.is_some(), "should resolve the npm alias package");
+        let pkg = resolved.unwrap();
+        assert_eq!(pkg.key, "buffer@npm:6.0.3");
+        assert_eq!(pkg.version, "6.0.3");
+
+        // Pruning for workspace "a" should include the npm buffer package
+        let subgraph = lockfile
+            .subgraph(
+                &["packages/a".to_string()],
+                &["buffer@npm:6.0.3".to_string()],
+            )
+            .unwrap();
+        let encoded = String::from_utf8(subgraph.encode().unwrap()).unwrap();
+        assert!(
+            encoded.contains("buffer@npm:buffer@6.0.3"),
+            "pruned lockfile should contain the npm alias entry"
+        );
+    }
+
     #[test]
     fn test_berry_manifest_into_parts_merges_correctly() {
         let mut default_catalog = Map::new();

crates/turborepo-repository/src/package_graph/dep_splitter.rs

@@ -151,6 +151,28 @@ impl<'a> DependencyVersion<'a> {
         )
     }
 
+    /// Returns true if this dependency uses an npm alias (`npm:pkg@version`).
+    /// This is distinct from a plain npm range (`npm:^1.0.0`). When a package
+    /// name is present in the specifier, the user is explicitly requesting an
+    /// npm registry package, which should never resolve to a workspace.
+    fn is_npm_alias(&self) -> bool {
+        if self.protocol != Some("npm") {
+            return false;
+        }
+        // npm alias format: `npm:<package-name>@<version>`
+        // A scoped package looks like `npm:@scope/pkg@version`, so we need to
+        // handle the leading `@` carefully.
+        let name_and_version = if let Some(rest) = self.version.strip_prefix('@') {
+            // Scoped: skip past scope to find the `@version` separator
+            rest.find('@').map(|i| i + 1)
+        } else {
+            self.version.find('@')
+        };
+        // If there's an `@` separating a package name from a version, and the
+        // part before it isn't empty, this is an alias.
+        name_and_version.is_some_and(|i| i > 0)
+    }
+
     fn is_external(&self) -> bool {
         // The npm protocol for yarn by default still uses the workspace package if the
         // workspace version is in a compatible semver range. See https://github.com/yarnpkg/berry/discussions/4015
@@ -185,6 +207,9 @@ impl<'a> DependencyVersion<'a> {
                 // Other protocols are assumed to be external references ("github:", etc)
                 false
             }
+            // npm: alias syntax (e.g. `npm:buffer@6.0.3` or `npm:@scope/pkg@^1.0.0`)
+            // means the user explicitly wants the npm registry package, not a workspace.
+            Some("npm") if self.is_npm_alias() => false,
             _ if self.version == "*" => true,
             _ if package_version.is_empty() => {
                 // The workspace version of this package does not contain a version, no version
@@ -253,6 +278,9 @@ mod test {
     #[test_case("1.2.3", Some("foo"), "workspace:@scope/foo@*", Some("@scope/foo"), true ; "handles pnpm alias star")]
     #[test_case("1.2.3", Some("foo"), "workspace:@scope/foo@~", Some("@scope/foo"), true ; "handles pnpm alias tilde")]
     #[test_case("1.2.3", Some("foo"), "workspace:@scope/foo@^", Some("@scope/foo"), true ; "handles pnpm alias caret")]
+    #[test_case("6.0.3", Some("buffer"), "npm:buffer@6.0.3", None, true ; "handles npm alias with matching workspace name")]
+    #[test_case("1.2.3", None, "npm:other-pkg@^1.0.0", None, true ; "handles npm alias with different package name")]
+    #[test_case("1.2.3", None, "npm:@scope/foo@^1.0.0", None, true ; "handles npm alias with scoped package")]
     #[test_case("1.2.3", None, "1.2.3", None, false ; "no workspace linking")]
     #[test_case("1.2.3", None, "workspace:1.2.3", Some("@scope/foo"), false ; "no workspace linking with protocol")]
     #[test_case("", None, "1.2.3", None, true ; "no workspace package version")]
@@ -318,6 +346,21 @@ mod test {
                     transitive_dependencies: None,
                 },
             );
+            map.insert(
+                PackageName::Other("buffer".to_string()),
+                PackageInfo {
+                    package_json: PackageJson {
+                        version: Some("6.0.3".to_string()),
+                        ..Default::default()
+                    },
+                    package_json_path: AnchoredSystemPathBuf::from_raw(
+                        ["packages", "buffer", "package.json"].join(std::path::MAIN_SEPARATOR_STR),
+                    )
+                    .unwrap(),
+                    unresolved_external_dependencies: None,
+                    transitive_dependencies: None,
+                },
+            );
             map
         };
 
@@ -336,6 +379,17 @@ mod test {
         );
     }
 
+    #[test_case("npm:buffer@6.0.3", true ; "npm alias unscoped")]
+    #[test_case("npm:@scope/pkg@^1.0.0", true ; "npm alias scoped")]
+    #[test_case("npm:^1.2.3", false ; "npm range")]
+    #[test_case("npm:*", false ; "npm wildcard")]
+    #[test_case("workspace:*", false ; "workspace protocol")]
+    #[test_case("^1.0.0", false ; "bare range")]
+    fn test_is_npm_alias(version: &str, expected: bool) {
+        let dep = DependencyVersion::new(version);
+        assert_eq!(dep.is_npm_alias(), expected, "is_npm_alias({version})");
+    }
+
     #[test_case("1.2.3", None ; "non-workspace")]
     #[test_case("workspace:1.2.3", None ; "workspace version")]
     #[test_case("workspace:*", None ; "workspace any")]

lockfile-tests/fixtures/berry-npm-alias/.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+
+enableTransparentWorkspaces: false

lockfile-tests/fixtures/berry-npm-alias/meta.json

@@ -0,0 +1,6 @@
+{
+  "packageManager": "yarn-berry",
+  "packageManagerVersion": "yarn@4.4.0",
+  "lockfileName": "yarn.lock",
+  "frozenInstallCommand": ["yarn", "install", "--immutable"]
+}

lockfile-tests/fixtures/berry-npm-alias/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "berry-npm-alias",
+  "version": "0.0.0",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "packageManager": "yarn@4.4.0"
+}

lockfile-tests/fixtures/berry-npm-alias/packages/a/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "a",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "buffer": "npm:buffer@6.0.3"
+  }
+}

lockfile-tests/fixtures/berry-npm-alias/packages/buffer/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "buffer",
+  "version": "6.0.3",
+  "private": true
+}

lockfile-tests/fixtures/berry-npm-alias/turbo.json

@@ -0,0 +1,5 @@
+{
+  "tasks": {
+    "build": {}
+  }
+}

lockfile-tests/fixtures/berry-npm-alias/yarn.lock

@@ -0,0 +1,50 @@
+# This file is generated by running "yarn install" inside your project.
+# Manual changes might be lost - proceed with caution!
+
+__metadata:
+  version: 8
+  cacheKey: 10c0
+
+"a@workspace:packages/a":
+  version: 0.0.0-use.local
+  resolution: "a@workspace:packages/a"
+  dependencies:
+    buffer: "npm:buffer@6.0.3"
+  languageName: unknown
+  linkType: soft
+
+"base64-js@npm:^1.3.1":
+  version: 1.5.1
+  resolution: "base64-js@npm:1.5.1"
+  checksum: 10c0/f23823513b63173a001030fae4f2dabe283b99a9d324ade3ad3d148e218134676f1ee8568c877cd79ec1c53158dcf2d2ba527a97c606618928ba99dd930102bf
+  languageName: node
+  linkType: hard
+
+"berry-npm-alias@workspace:.":
+  version: 0.0.0-use.local
+  resolution: "berry-npm-alias@workspace:."
+  languageName: unknown
+  linkType: soft
+
+"buffer@npm:buffer@6.0.3":
+  version: 6.0.3
+  resolution: "buffer@npm:6.0.3"
+  dependencies:
+    base64-js: "npm:^1.3.1"
+    ieee754: "npm:^1.2.1"
+  checksum: 10c0/2a905fbbcde73cc5d8bd18d1caa23715d5f83a5935867c2329f0ac06104204ba7947be098fe1317fbd8830e26090ff8e764f08cd14fefc977bb248c3487bcbd0
+  languageName: node
+  linkType: hard
+
+"buffer@workspace:packages/buffer":
+  version: 0.0.0-use.local
+  resolution: "buffer@workspace:packages/buffer"
+  languageName: unknown
+  linkType: soft
+
+"ieee754@npm:^1.2.1":
+  version: 1.2.1
+  resolution: "ieee754@npm:1.2.1"
+  checksum: 10c0/b0782ef5e0935b9f12883a2e2aa37baa75da6e66ce6515c168697b42160807d9330de9a32ec1ed73149aea02e0d822e572bca6f1e22bdcbd2149e13b050b17bb
+  languageName: node
+  linkType: hard