@mui/internal-code-infra 0.0.4-canary.1 → 0.0.4-canary.100

package/src/utils/pnpm.mjs

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 
+import { findWorkspaceDir } from '@pnpm/find-workspace-dir';
 import { $ } from 'execa';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as semver from 'semver';
+import { parseDocument, isMap } from 'yaml';
+
+/** Canonical npm registry URL, in the form `getPublishRegistry` returns. */
+const NPMJS_REGISTRY = 'https://registry.npmjs.org/';
 
 /**
  * @typedef {Object} PrivatePackage
@@ -46,8 +51,8 @@ import * as semver from 'semver';
  * @typedef {Object} GetWorkspacePackagesOptions
  * @property {string|null} [sinceRef] - Git reference to filter changes since
  * @property {boolean} [publicOnly=false] - Whether to filter to only public packages
- * @property {boolean} [nonPublishedOnly=false] - Whether to filter to only non-published packages. It by default means public packages yet to be published.
  * @property {string} [cwd] - Current working directory to run pnpm command in
+ * @property {string[]} [filter] - Same as filtering packages with --filter in pnpm. Only include packages matching the filter. See https://pnpm.io/filtering.
  */
 
 /**
@@ -58,10 +63,6 @@ import * as semver from 'semver';
  * @returns {Promise<PublicPackage[]>} Array of packages
  *
  * @overload
- * @param {{ nonPublishedOnly: true } & GetWorkspacePackagesOptions} [options={}] - Options for filtering packages
- * @returns {Promise<PublicPackage[]>} Array of packages
- *
- * @overload
  * @param {{ publicOnly?: false | undefined } & GetWorkspacePackagesOptions} [options={}] - Options for filtering packages
  * @returns {Promise<PrivatePackage[]>} Array of packages
  *
@@ -73,15 +74,38 @@ import * as semver from 'semver';
  * @returns {Promise<(PrivatePackage | PublicPackage)[]>} Array of packages
  */
 export async function getWorkspacePackages(options = {}) {
-  const { sinceRef = null, publicOnly = false, nonPublishedOnly = false } = options;
+  const { sinceRef = null, publicOnly = false, filter = [] } = options;
+
+  /**
+   * Run `pnpm ls` with the given --filter args and return the parsed list.
+   * @param {string[]} filterArg
+   * @returns {Promise<PnpmListResultItem[]>}
+   */
+  const listPackages = async (filterArg) => {
+    const result = await $({ cwd: options.cwd })`pnpm ls -r --json --depth -1 ${filterArg}`;
+    return JSON.parse(result.stdout);
+  };
 
-  // Build command with conditional filter
-  const filterArg = sinceRef ? ['--filter', `...[${sinceRef}]`] : [];
-  const result = options.cwd
-    ? await $({ cwd: options.cwd })`pnpm ls -r --json --depth -1 ${filterArg}`
-    : await $`pnpm ls -r --json --depth -1 ${filterArg}`;
-  /** @type {PnpmListResultItem[]} */
-  const packageData = JSON.parse(result.stdout);
+  // pnpm ORs --filter args, so intersect "matches filter" with "changed since ref"
+  // in JS. The `...[ref]` selector includes dependents of changed packages, so a
+  // package whose `workspace:*` dependency changed is treated as changed too. This
+  // keeps consumers from getting duplicate copies when only a leaf package is
+  // republished but its dependents still pin the previous version.
+  const patternFilterArg = filter.flatMap((f) => ['--filter', f]);
+  const [candidatePackages, changedPackages] = await Promise.all([
+    listPackages(patternFilterArg),
+    // null when no sinceRef (skip the constraint); [] when nothing changed.
+    sinceRef ? listPackages(['--filter', `...[${sinceRef}]`]) : Promise.resolve(null),
+  ]);
+  let packageData = candidatePackages;
+  if (changedPackages) {
+    // sinceRef given but nothing changed → no packages, regardless of filter.
+    if (changedPackages.length === 0) {
+      return [];
+    }
+    const changedPaths = new Set(changedPackages.map((pkg) => pkg.path));
+    packageData = packageData.filter((pkg) => changedPaths.has(pkg.path));
+  }
 
   // Filter packages based on options
   const filteredPackages = packageData.flatMap((pkg) => {
@@ -99,24 +123,115 @@ export async function getWorkspacePackages(options = {}) {
     ];
   });
 
-  if (nonPublishedOnly) {
-    // Check if any of the packages are new/need manual publishing first.
-    const filteredPublicPackages = filteredPackages.filter((pkg) => !pkg.isPrivate);
+  return filteredPackages;
+}
 
-    const results = await Promise.all(
-      filteredPublicPackages.map(async (pkg) => {
-        const url = `${process.env.npm_config_registry || 'https://registry.npmjs.org'}/${pkg.name}`;
-        return fetch(url).then((res) => res.status === 404);
-      }),
+/**
+ * Resolve the registry a package will be published to.
+ *
+ * Only `publishConfig.registry` and the ambient `npm_config_registry` are
+ * consulted — `.npmrc` layering and `@scope:registry` entries are not.
+ *
+ * @param {string} packagePath - Path to the package directory
+ * @returns {Promise<string>} Normalized registry URL, ending in a slash
+ */
+export async function getPublishRegistry(packagePath) {
+  const packageJson = await readPackageJson(packagePath);
+  const registry =
+    packageJson.publishConfig?.registry || process.env.npm_config_registry || NPMJS_REGISTRY;
+
+  // Normalizing through the URL parser keeps host casing and default ports from
+  // defeating the equality check in `requiresTrustedPublisherBootstrap`. The
+  // trailing slash is required because `new URL(name, base)` replaces the last
+  // path segment of a base that lacks one, mangling registries served under a
+  // path prefix such as Artifactory's `/api/npm/<repo>`.
+  let registryUrl;
+  try {
+    registryUrl = new URL(registry);
+  } catch (error) {
+    // Node's own message names neither the offending value nor where it came
+    // from, leaving the operator to bisect package.json files mid-release.
+    throw new Error(
+      `Invalid publish registry ${JSON.stringify(registry)} for the package at ${packagePath}`,
+      { cause: error },
     );
-    return filteredPublicPackages.filter((_pkg, index) => !!results[index]);
   }
+  registryUrl.pathname = `${registryUrl.pathname.replace(/\/+$/, '')}/`;
+  return registryUrl.href;
+}
 
-  return filteredPackages;
+/**
+ * Get the version to release from the workspace-root package.json.
+ *
+ * Resolves the workspace root so the version is the monorepo's regardless of
+ * which directory publish runs from.
+ *
+ * @param {string} [cwd] - Directory to resolve the workspace root from
+ * @returns {Promise<string | null>} Version string, or null when absent/invalid
+ */
+export async function getReleaseVersion(cwd = process.cwd()) {
+  const workspaceDir = (await findWorkspaceDir(cwd)) ?? cwd;
+  const { version } = await readPackageJson(workspaceDir);
+  return version ? semver.valid(version) : null;
+}
+
+/**
+ * Whether a registry requires a package to exist before CI can publish to it.
+ * @param {string} registry - Normalized registry URL
+ * @returns {boolean}
+ */
+function requiresTrustedPublisherBootstrap(registry) {
+  // npm won't attach a Trusted Publisher to a name that doesn't exist yet. No
+  // other registry we publish to has an equivalent step.
+  return registry === NPMJS_REGISTRY;
 }
 
 /**
- * Get package version info from registry
+ * Filter to the packages that must be published by hand before CI can take over.
+ *
+ * A brand new package has to be pushed once manually (see
+ * `code-infra publish-new-package`) before the OIDC-based workflow can publish
+ * it, so the release fails with a clear message instead of a confusing 404
+ * midway through. See {@link getPackageVersionInfo} for the version-level check.
+ *
+ * @param {PublicPackage[]} packages - Packages to check
+ * @returns {Promise<PublicPackage[]>} The subset needing a manual first publish
+ */
+export async function getPackagesNeedingManualPublish(packages) {
+  const results = await Promise.all(
+    packages.map(async (pkg) => {
+      const registry = await getPublishRegistry(pkg.path);
+      if (!requiresTrustedPublisherBootstrap(registry)) {
+        return false;
+      }
+
+      // HEAD, because only the status matters — a packument runs to megabytes.
+      const res = await fetch(new URL(pkg.name, registry), { method: 'HEAD' });
+      if (res.status === 404) {
+        return true;
+      }
+      if (!res.ok) {
+        // Anything else (401, 5xx, a proxy hiccup) tells us nothing about
+        // whether the package exists. Treating it as "already published" would
+        // silently disable the check, so fail loudly instead.
+        throw new Error(
+          `Failed to check whether ${pkg.name} exists on ${registry}: HTTP ${res.status}`,
+        );
+      }
+      return false;
+    }),
+  );
+
+  return packages.filter((_pkg, index) => results[index]);
+}
+
+/**
+ * Get package version info from registry.
+ *
+ * Resolves through `pnpm view`, which reports a lookup failure the same way it
+ * reports a missing version. Use {@link getPackagesNeedingManualPublish} where
+ * absence has to be told apart from an error.
+ *
  * @param {string} packageName - Name of the package
  * @param {string} baseVersion - Base version to check
  * @returns {Promise<VersionInfo>} Version information
@@ -148,11 +263,17 @@ export async function getPackageVersionInfo(packageName, baseVersion) {
   }
 }
 
+/**
+ * @typedef {Object} PublishSummaryEntry
+ * @property {string} name
+ * @property {string} version
+ */
+
 /**
  * Publish packages with the given options
  * @param {PublicPackage[]} packages - Packages to publish
  * @param {PublishOptions} [options={}] - Publishing options
- * @returns {Promise<void>}
+ * @returns {Promise<PublishSummaryEntry[]>}
  */
 export async function publishPackages(packages, options = {}) {
   const args = [];
@@ -172,7 +293,202 @@ export async function publishPackages(packages, options = {}) {
     args.push('--no-git-checks');
   }
 
-  await $({ stdio: 'inherit' })`pnpm -r publish --access public --tag=${tag} ${args}`;
+  const workspaceDir = await findWorkspaceDir(process.cwd());
+  if (!workspaceDir) {
+    throw new Error('Could not find pnpm workspace root');
+  }
+  const summaryPath = path.join(workspaceDir, 'pnpm-publish-summary.json');
+
+  // Clean up any leftover summary file from a previous run
+  await fs.rm(summaryPath, { force: true });
+
+  await $({
+    stdio: 'inherit',
+    env: { npm_config_loglevel: 'warn' },
+  })`pnpm -r publish --access public --tag=${tag} --report-summary ${args}`;
+
+  const summary = JSON.parse(await fs.readFile(summaryPath, 'utf-8'));
+  await fs.rm(summaryPath, { force: true });
+  return /** @type {PublishSummaryEntry[]} */ (summary.publishedPackages);
+}
+
+/**
+ * @typedef {Object} GetTransitiveDependenciesOptions
+ * @property {Map<string, string>} [workspacePathByName] - Map of workspace package name to directory path
+ * @property {boolean} [includeDev=true] - Whether to include devDependencies in the traversal
+ */
+
+/**
+ * The package a `workspace:` alias spec resolves to, if it is one.
+ *
+ * @param {string} spec - Dependency spec
+ * @returns {string | null} The aliased package name, or null for a plain spec
+ */
+function aliasTarget(spec) {
+  if (!spec.startsWith('workspace:')) {
+    return null;
+  }
+  const range = spec.slice('workspace:'.length);
+  // Search from 1 so a scoped name's own leading `@` isn't read as the separator.
+  const separator = range.indexOf('@', 1);
+  return separator === -1 ? null : range.slice(0, separator);
+}
+
+/**
+ * Get all transitive workspace dependencies for a set of packages.
+ *
+ * Only follows deps whose version spec starts with `workspace:` (e.g. `workspace:*`
+ * or `workspace:^`), meaning they are sourced directly from the monorepo. An
+ * alias spec (`workspace:@scope/name@range`) is followed to the package it
+ * targets, which need not match the dependency key. Pinned
+ * external versions (e.g. `^1.0.0`) are ignored even when the package name exists
+ * in the workspace. Traverses `dependencies` and optionally `devDependencies`.
+ * Results are cached per package so each package is read from disk at most once
+ * regardless of how many roots depend on it.
+ *
+ * @param {string[]} packageNames - Package names to start the traversal from
+ * @param {GetTransitiveDependenciesOptions} [options]
+ * @returns {Promise<Set<string>>} All reachable workspace package names, including the input packages themselves
+ */
+export async function getTransitiveDependencies(packageNames, options = {}) {
+  const { includeDev = true, workspacePathByName = new Map() } = options;
+
+  /** @type {Map<string, Promise<Set<string>>>} */
+  const cache = new Map();
+
+  /**
+   * @param {string} packageName
+   * @returns {Promise<Set<string>>}
+   */
+  function collectDeps(packageName) {
+    const cached = cache.get(packageName);
+    if (cached) {
+      return cached;
+    }
+
+    const promise = (async () => {
+      const packagePath = workspacePathByName.get(packageName);
+      if (!packagePath) {
+        throw new Error(`Workspace "${packageName}" not found`);
+      }
+
+      const pkgJson = await readPackageJson(packagePath);
+      const allDepEntries = [
+        ...Object.entries(pkgJson.dependencies ?? {}),
+        ...(includeDev ? Object.entries(pkgJson.devDependencies ?? {}) : []),
+      ];
+      const workspaceDeps = allDepEntries.flatMap(([dep, spec]) => {
+        if (typeof spec !== 'string' || !spec.startsWith('workspace:')) {
+          return [];
+        }
+        // An aliased spec (`workspace:@scope/name@range`) names the workspace
+        // package it resolves to, which need not match the dependency key.
+        const name = aliasTarget(spec) ?? dep;
+        return workspacePathByName.has(name) ? [name] : [];
+      });
+
+      const recursiveResults = await Promise.all(workspaceDeps.map(collectDeps));
+      return new Set([...workspaceDeps, ...recursiveResults.flatMap((s) => [...s])]);
+    })();
+
+    cache.set(packageName, promise);
+    return promise;
+  }
+
+  for (const name of packageNames) {
+    if (!workspacePathByName.has(name)) {
+      throw new Error(`Workspace "${name}" not found`);
+    }
+  }
+
+  const results = await Promise.all(packageNames.map(collectDeps));
+  return new Set([...packageNames, ...results.flatMap((s) => [...s])]);
+}
+
+/**
+ * Pure validation logic: given a publish set and workspace maps, checks that all
+ * transitive hard workspace dependencies are covered and none are private.
+ *
+ * A hard dependency is one listed in `dependencies` (not `peerDependencies` or
+ * `devDependencies`) using a `workspace:` version specifier (e.g. `workspace:*` or
+ * `workspace:^`). Peer dependencies are never bundled and dev dependencies are not installed
+ * on consumer devices - both are excluded regardless of version specifier. Pinned-version
+ * references in `dependencies` are also excluded - they resolve from the registry and do
+ * not need to be co-published.
+ *
+ * @param {PublicPackage[]} packages - The packages intended for publishing
+ * @param {Map<string, PublicPackage | PrivatePackage>} workspacePackageByName - All workspace packages by name
+ * @param {Map<string, string>} workspacePathByName - Map of workspace package name to directory path
+ * @returns {Promise<{issues: string[]}>}
+ *   List of human-readable issue strings. Empty when the dependency set is valid.
+ * @internal
+ */
+export async function checkPublishDependencies(
+  packages,
+  workspacePackageByName,
+  workspacePathByName,
+) {
+  const publishedNames = new Set(packages.map((pkg) => pkg.name));
+
+  const transitiveDeps = await getTransitiveDependencies(
+    packages.map((pkg) => pkg.name),
+    { includeDev: false, workspacePathByName },
+  );
+
+  /** @type {Set<string>} */
+  const privateButRequired = new Set();
+  /** @type {Set<string>} */
+  const missingFromPublish = new Set();
+
+  for (const depName of transitiveDeps) {
+    if (publishedNames.has(depName)) {
+      continue;
+    }
+    const workspacePkg = workspacePackageByName.get(depName);
+    if (workspacePkg?.isPrivate) {
+      privateButRequired.add(depName);
+    } else {
+      missingFromPublish.add(depName);
+    }
+  }
+
+  /** @type {string[]} */
+  const issues = [];
+
+  if (privateButRequired.size > 0) {
+    issues.push(
+      `The following private workspace packages are required as dependencies but cannot be published: ${[...privateButRequired].join(', ')}`,
+    );
+  }
+
+  if (missingFromPublish.size > 0) {
+    issues.push(
+      `The following workspace packages are required as dependencies but are not included in the publish set: ${[...missingFromPublish].join(', ')}. Add them to the --filter list.`,
+    );
+  }
+
+  return { issues };
+}
+
+/**
+ * Validate that a set of packages covers all of their transitive hard workspace dependencies,
+ * and that none of those dependencies are private (which would make them unpublishable).
+ *
+ * @param {PublicPackage[]} packages - The packages intended for publishing
+ * @returns {Promise<{issues: string[]}>}
+ *   List of human-readable issue strings. Empty when the dependency set is valid.
+ */
+export async function validatePublishDependencies(packages) {
+  const allWorkspacePackages = await getWorkspacePackages();
+
+  const workspacePackageByName = /** @type {Map<string, PublicPackage | PrivatePackage>} */ (
+    new Map(allWorkspacePackages.flatMap((pkg) => (pkg.name ? [[pkg.name, pkg]] : [])))
+  );
+  const workspacePathByName = new Map(
+    allWorkspacePackages.flatMap((pkg) => (pkg.name ? [[pkg.name, pkg.path]] : [])),
+  );
+
+  return checkPublishDependencies(packages, workspacePackageByName, workspacePathByName);
 }
 
 /**
@@ -196,6 +512,213 @@ export async function writePackageJson(packagePath, packageJson) {
   await fs.writeFile(path.join(packagePath, 'package.json'), content);
 }
 
+/**
+ * Write the computed overrides into whichever manifest already defines
+ * overrides — preferring pnpm-workspace.yaml, falling back to package.json
+ * `pnpm.overrides`, defaulting to pnpm-workspace.yaml — and persist the result.
+ * A missing pnpm-workspace.yaml is treated as empty, so a fresh file is created
+ * with just the `overrides:` block. Rejects a `resolutions` field in
+ * package.json because pnpm 11 silently ignores it.
+ *
+ * @param {string} workspaceDir - Workspace root directory
+ * @param {Record<string, string>} overrides - Overrides to apply
+ * @returns {Promise<void>}
+ */
+export async function writeOverridesToWorkspace(workspaceDir, overrides) {
+  const workspaceYamlPath = path.join(workspaceDir, 'pnpm-workspace.yaml');
+  const yamlPromise = fs.readFile(workspaceYamlPath, { encoding: 'utf8' }).catch((error) => {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') {
+      throw error;
+    }
+    return '';
+  });
+  const [rootPackageJson, yamlSource] = await Promise.all([
+    readPackageJson(workspaceDir),
+    yamlPromise,
+  ]);
+
+  const { resolutions } = rootPackageJson;
+  if (resolutions && Object.keys(resolutions).length > 0) {
+    throw new Error(
+      'Found a "resolutions" field in package.json. pnpm 11 ignores it silently. ' +
+        'Move those entries into the "overrides:" key of pnpm-workspace.yaml.',
+    );
+  }
+
+  // Parsed once, reused for both the read (does it have overrides?) and the write.
+  const doc = parseDocument(yamlSource);
+  const existing = doc.get('overrides');
+  const workspaceHasOverrides = isMap(existing) && existing.items.length > 0;
+
+  const pnpm = /** @type {{ overrides?: Record<string, string> } | undefined} */ (
+    rootPackageJson.pnpm
+  );
+  const packageJsonOverrides = pnpm?.overrides;
+
+  // Write where overrides already live; default to the workspace file.
+  if (
+    !workspaceHasOverrides &&
+    packageJsonOverrides &&
+    Object.keys(packageJsonOverrides).length > 0
+  ) {
+    await writePackageJson(workspaceDir, {
+      ...rootPackageJson,
+      pnpm: { ...pnpm, overrides: { ...packageJsonOverrides, ...overrides } },
+    });
+    return;
+  }
+
+  for (const [name, version] of Object.entries(overrides)) {
+    doc.setIn(['overrides', name], version);
+  }
+  await fs.writeFile(workspaceYamlPath, doc.toString());
+}
+
+/**
+ * Map a package name onto a different npm scope.
+ * @param {string} name - Package name, e.g. `@base-ui/mosaic`
+ * @param {string} fromScope - Scope to replace, e.g. `@base-ui`
+ * @param {string} toScope - Replacement scope, e.g. `@base-ui-private`
+ * @returns {string | null} The renamed package, or null when the scope doesn't match
+ */
+function renameScope(name, fromScope, toScope) {
+  const prefix = `${fromScope}/`;
+  return name.startsWith(prefix) ? `${toScope}/${name.slice(prefix.length)}` : null;
+}
+
+/**
+ * Move the publishable workspace packages in one scope to another.
+ *
+ * Only packages that are part of the workspace are touched, so dependencies
+ * that merely share the scope but come from the registry (say `@base-ui/react`
+ * alongside a workspace `@base-ui/mosaic`) are left alone. Dependents keep the
+ * original dependency name and gain a `workspace:` alias, so imports in the
+ * repo resolve exactly as before.
+ *
+ * @param {(PublicPackage | PrivatePackage)[]} packages - All workspace packages
+ * @param {string} fromScope - Scope to move away from
+ * @param {string} toScope - Scope to move to
+ * @returns {Promise<Map<string, string>>} Old package name to new package name
+ */
+export async function renameWorkspaceScope(packages, fromScope, toScope) {
+  // Renaming a scope onto itself only rewrites every manifest to itself. The
+  // CLI rejects this earlier, but the guard belongs with the operation so a
+  // direct caller cannot trip the silent churn either.
+  if (fromScope === toScope) {
+    throw new Error(`Cannot rename ${fromScope} to itself.`);
+  }
+
+  /** @type {Map<string, string>} */
+  const renamed = new Map();
+
+  for (const pkg of packages) {
+    if (pkg.isPrivate) {
+      continue;
+    }
+    const newName = renameScope(pkg.name, fromScope, toScope);
+    if (newName) {
+      renamed.set(pkg.name, newName);
+    }
+  }
+
+  // A rename that lands on a name another package keeps would leave the
+  // workspace with two packages sharing a name. Catch it up front, before any
+  // manifest is written.
+  /** @type {Map<string, string>} */
+  const finalNames = new Map();
+  for (const pkg of packages) {
+    if (!pkg.name) {
+      continue;
+    }
+    const finalName = renamed.get(pkg.name) ?? pkg.name;
+    const owner = finalNames.get(finalName);
+    if (owner) {
+      throw new Error(
+        `Cannot rename ${fromScope} to ${toScope}: ${pkg.name} and ${owner} would both be named ${finalName}.`,
+      );
+    }
+    finalNames.set(finalName, pkg.name);
+  }
+
+  // Rewrite in memory first. A dependency that cannot be pointed at its renamed
+  // package has to fail before anything is written, or the workspace is left
+  // half renamed with nothing to restore it.
+  const rewritten = await Promise.all(
+    packages.map(async (pkg) => {
+      const packageJson = await readPackageJson(pkg.path);
+      const label = pkg.name ?? pkg.path;
+      /** @type {string[]} */
+      const problems = [];
+      let changed = false;
+
+      const newName = pkg.name ? renamed.get(pkg.name) : undefined;
+      if (newName) {
+        packageJson.name = newName;
+        changed = true;
+      }
+
+      // peerDependencies are deliberately absent: a peer is supplied by the
+      // consumer, who installs the package under its original name. An alias
+      // range would be unsatisfiable for them.
+      for (const deps of [
+        packageJson.dependencies,
+        packageJson.devDependencies,
+        packageJson.optionalDependencies,
+      ]) {
+        if (!deps) {
+          continue;
+        }
+        for (const [depName, spec] of Object.entries(deps)) {
+          if (!spec) {
+            continue;
+          }
+
+          const existingTarget = aliasTarget(spec);
+          if (existingTarget) {
+            if (renamed.has(existingTarget)) {
+              problems.push(
+                `"${depName}" in ${label} already aliases ${existingTarget}, which is being renamed. Point it at the package directly so it can be rewritten.`,
+              );
+            }
+            // Otherwise it already aliases what it should, as a re-run does.
+            continue;
+          }
+
+          const target = renamed.get(depName);
+          if (!target) {
+            continue;
+          }
+          if (!spec.startsWith('workspace:')) {
+            // Only `workspace:` specs can be aliased. Anything else would keep
+            // resolving the original name from the registry after the rename.
+            problems.push(
+              `"${depName}" in ${label} is required as "${spec}" rather than a workspace: dependency, so it cannot be pointed at ${target}.`,
+            );
+            continue;
+          }
+          deps[depName] = `workspace:${target}@${spec.slice('workspace:'.length)}`;
+          changed = true;
+        }
+      }
+
+      return { path: pkg.path, packageJson, changed, problems };
+    }),
+  );
+
+  const problems = rewritten.flatMap((entry) => entry.problems);
+  if (problems.length > 0) {
+    throw new Error(`Cannot rename ${fromScope} to ${toScope}:\n  ${problems.join('\n  ')}`);
+  }
+
+  await Promise.all(
+    rewritten
+      .filter((entry) => entry.changed)
+      .map((entry) => writePackageJson(entry.path, entry.packageJson)),
+  );
+
+  return renamed;
+}
+
 /**
  * Resolve a package@version specifier to an exact version
  * @param {string} packageSpec - Package specifier in format "package@version"

package/src/utils/testUtils.mjs

@@ -0,0 +1,53 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { onTestFinished } from 'vitest';
+
+import { writePackageJson } from './pnpm.mjs';
+
+/**
+ * Creates a temporary directory and registers an `onTestFinished` hook to
+ * remove it automatically when the current test ends — even if the test throws.
+ *
+ * @returns {Promise<string>} The path of the created temporary directory.
+ */
+export async function makeTempDir() {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'code-infra-test-'));
+  onTestFinished(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+  return tmpDir;
+}
+
+/**
+ * Write a package.json into a subdirectory of a temp workspace.
+ *
+ * @param {string} root - Workspace root
+ * @param {string} dir - Subdirectory to create
+ * @param {object} pkgJson - Manifest contents
+ * @returns {Promise<string>} The package directory
+ */
+export async function writePackage(root, dir, pkgJson) {
+  const pkgDir = path.join(root, dir);
+  await fs.mkdir(pkgDir, { recursive: true });
+  await writePackageJson(pkgDir, pkgJson);
+  return pkgDir;
+}
+
+/**
+ * @param {string} name
+ * @param {string} pkgPath
+ * @returns {import('./pnpm.mjs').PublicPackage}
+ */
+export function publicPkg(name, pkgPath) {
+  return { name, version: '1.0.0', path: pkgPath, isPrivate: false };
+}
+
+/**
+ * @param {string} name
+ * @param {string} pkgPath
+ * @returns {import('./pnpm.mjs').PrivatePackage}
+ */
+export function privatePkg(name, pkgPath) {
+  return { name, version: '1.0.0', path: pkgPath, isPrivate: true };
+}