bun-nested-workspace 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# bun-nested-workspace
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Embed a checkout of another Bun workspace repository into a subdirectory of your Bun workspace, and keep the root `package.json` and `bun.lock` of the host in sync with it.
+
+The nested repository stays a self-contained project with its own root `package.json` and `bun.lock`.
+Its packages, such as `nested/apps/*` and `nested/packages/*`, become workspaces of the host, while its root does not.
+The host installs none of the dependencies of the nested root `package.json` and cannot run its scripts.
+Bun reads catalogs, overrides, patches, and trusted dependencies from the workspace root only, and resolves the whole workspace from a single lockfile.
+This package carries those root fields over to the host and merges the nested lockfile into the host lockfile, so the nested packages build in the host with the same dependency versions as on their own.
+
+## Install
+
+The CLI runs before the host dependencies are installed, so run it with `bunx`:
+
+```sh
+bunx bun-nested-workspace
+```
+
+It requires Bun 1.2.19 or later, the first version that resolves `catalog:` dependencies from both catalog locations.
+
+## Setup
+
+Add the nested packages to the host workspaces and name the nested directory in the `bun-nested-workspace` field of the host `package.json`:
+
+```json
+{
+  "workspaces": ["apps/*", "nested/apps/*", "nested/packages/*"],
+  "bun-nested-workspace": {
+    "dir": "nested"
+  }
+}
+```
+
+Both modes fail when the host `workspaces` patterns miss a workspace package of the nested repository.
+
+The config takes these fields:
+
+- `dir`: the nested checkout directory, relative to the host root.
+- `fields`: the root fields to sync, a subset of `catalog`, `catalogs`, `overrides`, `patchedDependencies`, and `trustedDependencies`; all of them when omitted.
+- `synced`: the names of entries that came from the nested repository, maintained by the sync; commit it and do not edit it by hand.
+
+## Sync
+
+Run the CLI in the host root after switching the nested checkout to another commit:
+
+```sh
+bunx bun-nested-workspace
+```
+
+The sync:
+
+1. Merges the configured root fields of the nested `package.json` into the host `package.json`.
+2. Merges the nested `bun.lock` into the host `bun.lock`.
+3. Runs `bun install` with the CLI arguments, such as `--lockfile-only` or `--ignore-scripts`.
+4. Fails if the install re-resolved own dependencies of host packages, or if the host does not resolve the nested packages as the nested lockfile does.
+
+Commit `package.json` and `bun.lock` after the sync.
+
+In a Docker build, run the sync with `--lockfile-only` in a stage that contains only the dependency files, before installing dependencies.
+`bun install` also needs the patch files and the install configuration, such as `bunfig.toml` and `.npmrc`, so keep them, along with any files they reference.
+A separate stage can strip the build context down to these files, so the Dockerfile does not list every workspace package:
+
+```dockerfile
+FROM oven/bun:1 AS manifests
+WORKDIR /app
+COPY . .
+RUN find . -type f ! -name package.json ! -name bun.lock ! -name '*.patch' ! -name bunfig.toml ! -name .npmrc -delete
+
+FROM oven/bun:1 AS deps
+WORKDIR /app
+COPY --from=manifests /app ./
+RUN bunx bun-nested-workspace --lockfile-only
+```
+
+Exclude `node_modules` and other large directories from the build context with `.dockerignore`.
+
+### Root fields
+
+- `catalog` and `catalogs` each stay where the host defines them; a field the host lacks goes next to the other catalog field, or into `workspaces`.
+  An array `workspaces` field becomes an object when a catalog needs it.
+- `overrides` and `trustedDependencies` are merged by package name.
+- `resolutions` on either side is an error while `overrides` are synced: Bun ignores `resolutions` once `overrides` is defined, so move its entries to `overrides`.
+- `trustedDependencies` stays in the host `package.json`, even empty, when either side defines it.
+  An explicit list replaces the default trusted list of Bun, so when only one side defines the field, the packages of the other side lose the default list; list the ones whose lifecycle scripts they need.
+  The sync warns when it adds the field to the host.
+- `patchedDependencies` paths are rewritten through the nested directory, such as `nested/patches/exceljs@4.4.0.patch`.
+
+A nested entry replaces a host entry with the same name, while the other host entries stay.
+The sync lists the host entries it replaced.
+A host entry equal to the nested one stays the host's own, so it survives when the nested repository drops it.
+An entry that came from the nested repository and is no longer there is removed; for patches, these are the patches inside the nested directory.
+A package version patched by both the host and the nested repository is an error.
+
+Bun warns when a nested patch targets a package version that the host does not install, such as a patched tool used only by the nested root.
+
+### Lockfile
+
+The nested lockfile entries replace the host entries, so the nested packages keep their versions.
+When a replaced entry no longer satisfies a dependency of a host package, the host package keeps its previous resolution as a nested lockfile entry.
+When neither satisfies the range, which Bun lockfiles occasionally contain, the dependency gets the highest satisfying version recorded in either lockfile.
+Ranges are checked as `bun install` applies them: an override replaces the declared range, and an `npm:` alias requires the package it names.
+`bun install` then resolves new dependencies of host packages and drops unused entries.
+
+After the install, the sync compares the direct dependencies of host packages with the original host lockfile.
+A dependency may only change to the version that the nested lockfile resolves at its root, and only within the host range.
+Any other change means either that the host lockfile did not pin the host dependencies, for example after an edit of a host `package.json` without `bun install`, or that the lockfile cannot record the host version next to the nested one.
+The latter happens to a host workspace without a name, because Bun records workspace-specific versions under the workspace name; name the workspace or align its range with the nested version.
+
+Only `bun.lock` with `lockfileVersion` 1 or 2 is supported, because the lockfile format is internal to Bun.
+
+## Check
+
+```sh
+bunx bun-nested-workspace --check
+```
+
+The check writes nothing, does not run `bun install`, and exits with code 1 when the host files lag behind the nested checkout.
+It reads the root `package.json` and `bun.lock` of the host and of the nested checkout only, so it relies on the nested `bun.lock` being up to date with the nested packages; `bun install --frozen-lockfile` in the nested directory verifies that.
+Use it in a non-blocking CI job that signals when a sync commit is due.
+
+It reports:
+
+- synced root fields of the host `package.json` that differ from the result of a sync;
+- nested workspaces whose `bun.lock` entries differ from the nested lockfile, which covers changed dependency declarations and added or removed packages;
+- direct dependencies of nested packages that the host resolves to other versions than the nested lockfile;
+- transitive dependencies of nested packages that the host resolves to other versions than the nested lockfile.
+
+The transitive check walks the dependency edges from the nested packages through both lockfiles at once and compares the resolved version and integrity of each edge.
+A different hoisting layout of the same versions is therefore not a difference.
+
+Limitations:
+
+- Peer dependencies are not walked.
+- Edges that the nested lockfile itself resolves outside their range are skipped, because the sync repairs them in the host.
+- The check does not verify that the host lockfile matches the host packages; `bun install --frozen-lockfile` does.
+- The check does not predict whether a sync would re-resolve own dependencies of host packages; only the sync detects it after `bun install`.
+
+## API
+
+The package exports the functions the CLI is built from:
+
+```ts
+import {
+  checkNestedWorkspace,
+  isInSync,
+  loadNestedWorkspace,
+  syncNestedWorkspace,
+} from "bun-nested-workspace"
+
+const check = checkNestedWorkspace(await loadNestedWorkspace(process.cwd()))
+if (!isInSync(check)) {
+  const result = await syncNestedWorkspace(process.cwd(), { installArgs: ["--lockfile-only"] })
+  if (result.ownDependencyChanges.length || !isInSync(result.check)) {
+    throw new Error("The sync changed host dependencies or did not keep the nested resolutions")
+  }
+}
+```
+
+`syncNestedWorkspace` writes the files and runs `bun install` before it checks the result, so a failed sync leaves the written files for inspection.
+Its `onManifestSync` option receives the replaced host entries and whether the sync added `trustedDependencies`, as soon as `package.json` is written and even when `bun install` then fails.
+
+Lower-level functions work on parsed files without touching the disk: `syncManifest`, `diffManifests`, `parseLockfile`, `relocateLockfile`, `applyManifestToLockfile`, `mergeLockfiles`, and the `find*` checks.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+import { a as syncNestedWorkspace, i as loadNestedWorkspace, n as checkNestedWorkspace, r as isInSync, t as BunInstallError, y as getErrorMessage } from "./workspace-BlJ1qGiO.mjs";
+// src/cli.ts
+const usage = `Usage:
+  bun-nested-workspace [bun install options]  Sync package.json and bun.lock, then run bun install
+  bun-nested-workspace --check                Exit with 1 if package.json or bun.lock lag behind the nested checkout
+
+Configure the nested directory in the "bun-nested-workspace" field of the host package.json.`;
+/** Runs the CLI with the given arguments in the given host root and returns the exit code. */
+async function runCli(args, root = process.cwd()) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(usage);
+		return 0;
+	}
+	try {
+		if (args.includes("--check")) {
+			const extra = args.filter((arg) => arg !== "--check");
+			if (extra.length) {
+				console.error(`--check takes no other options, got ${extra.join(" ")}\n\n${usage}`);
+				return 1;
+			}
+			return await runCheck(root);
+		}
+		return await runSync(root, args);
+	} catch (error) {
+		if (error instanceof BunInstallError) return error.exitCode;
+		console.error(getErrorMessage(error));
+		return 1;
+	}
+}
+async function runCheck(root) {
+	const workspace = await loadNestedWorkspace(root);
+	const result = checkNestedWorkspace(workspace);
+	if (isInSync(result)) {
+		console.log(`package.json and bun.lock are in sync with ${workspace.config.dir}`);
+		return 0;
+	}
+	console.error([
+		`package.json and bun.lock lag behind ${workspace.config.dir}:`,
+		...formatCheckResult(result),
+		"Run bun-nested-workspace without --check and commit package.json and bun.lock."
+	].join("\n"));
+	return 1;
+}
+async function runSync(root, installArgs) {
+	const { ownDependencyChanges, check } = await syncNestedWorkspace(root, {
+		installArgs,
+		onManifestSync: printManifestSync
+	});
+	let exitCode = 0;
+	if (ownDependencyChanges.length) {
+		console.error([
+			"The sync changed own dependencies of host packages.",
+			"Either the host bun.lock did not pin them: restore bun.lock, run bun install, commit bun.lock, and sync again.",
+			"Or the nested root resolves them outside the host range: align the host range with the nested version.",
+			...ownDependencyChanges.map(({ workspace, dependency, expected, actual }) => formatChange(`${workspace} > ${dependency}`, expected, actual))
+		].join("\n"));
+		exitCode = 1;
+	}
+	if (!isInSync(check)) {
+		console.error(["bun install did not keep the nested resolutions:", ...formatCheckResult(check)].join("\n"));
+		exitCode = 1;
+	}
+	return exitCode;
+}
+function printManifestSync({ overridden, addedTrustedDependencies }) {
+	if (overridden.length) console.log(["Nested entries replaced host entries:", ...overridden.map(formatOverridden)].join("\n"));
+	if (addedTrustedDependencies) console.warn([
+		"The sync added trustedDependencies to the host package.json.",
+		"Bun no longer applies its default trusted list, so host dependencies that relied on it no longer run their lifecycle scripts.",
+		"Add the ones the host needs to trustedDependencies."
+	].join("\n"));
+}
+/** Formats the differences of a failed check as indented lines grouped by kind. */
+function formatCheckResult(result) {
+	const section = (title, lines) => lines.length ? [`  ${title}:`, ...lines.map((line) => `  ${line}`)] : [];
+	return [
+		...section("package.json", result.manifest.map(formatDifference)),
+		...section("bun.lock workspaces", result.workspaces.map((workspacePath) => `  ${workspacePath}`)),
+		...section("direct dependencies", result.directDependencies.map(({ workspace, dependency, expected, actual }) => formatChange(`${workspace} > ${dependency}`, actual, expected))),
+		...section("transitive dependencies", result.transitiveDependencies.map(({ path, expected, actual }) => formatChange(path.join(" > "), actual, expected)))
+	];
+}
+function formatDifference({ path, expected, actual }) {
+	const format = (value) => value === void 0 ? void 0 : JSON.stringify(value);
+	return formatChange(path, format(actual), format(expected));
+}
+function formatOverridden({ field, name, hostValue, nestedValue }) {
+	return formatChange(`${field}.${name}`, JSON.stringify(hostValue), JSON.stringify(nestedValue));
+}
+/**
+* Formats a value change as an indented line, with a dash for a missing value.
+*
+* Lockfile entries of the same version can still differ in their registry or integrity.
+*/
+function formatChange(label, from, to) {
+	return from === to ? `  ${label}: ${from} (registry or integrity differs)` : `  ${label}: ${from ?? "—"} → ${to ?? "—"}`;
+}
+if (import.meta.main) process.exit(await runCli(process.argv.slice(2)));
+export {};

package/dist/index.d.mts

@@ -0,0 +1,304 @@
+type DependencyMap = Record<string, string>;
+type BunLockWorkspace = {
+  /**
+   * Optional in Bun lockfiles. When present, it is also used as the lookup
+   * context for workspace-scoped lock keys.
+   */
+  name?: string;
+  dependencies?: DependencyMap;
+  devDependencies?: DependencyMap;
+  optionalDependencies?: DependencyMap;
+  peerDependencies?: DependencyMap;
+};
+/**
+ * Metadata stored in a Bun package tuple.
+ *
+ * `bundled` is context-specific in Bun lockfiles: it belongs to entries under
+ * the package that bundles them and must not be blindly copied to another
+ * lock key when reusing a package tuple as a dedupe template.
+ */
+type BunPackageMeta = {
+  dependencies?: DependencyMap;
+  optionalDependencies?: DependencyMap;
+  peerDependencies?: DependencyMap;
+  /** Peer dependency names Bun treats as optional. */
+  optionalPeers?: string[];
+  /** True only inside the package subtree that actually bundles this entry. */
+  bundled?: boolean;
+  bin?: string | Record<string, string>;
+  os?: string | string[];
+  cpu?: string | string[];
+};
+/**
+ * Bun lockfile package tuple.
+ *
+ * Registry packages use `[spec, resolved, metadata, integrity]`, while git
+ * packages use `[spec, metadata, resolved, integrity]`. Bun omits trailing
+ * values freely in either form.
+ */
+type BunRegistryPackageEntry = [spec: string, resolved?: string, meta?: BunPackageMeta, integrity?: string];
+type BunGitPackageEntry = [spec: string, meta: BunPackageMeta, resolved?: string, integrity?: string];
+type BunPackageEntry = BunRegistryPackageEntry | BunGitPackageEntry;
+/** Parsed `bun.lock` sections that the tools read; Bun may preserve additional top-level keys. */
+type BunLockFile = {
+  lockfileVersion?: number;
+  configVersion?: number;
+  workspaces?: Record<string, BunLockWorkspace>;
+  /** Default catalog of the root `package.json`. */
+  catalog?: DependencyMap;
+  /** Named catalogs of the root `package.json`. */
+  catalogs?: Record<string, DependencyMap>;
+  /** Canonical map Bun writes for package.json overrides and resolutions. */
+  overrides?: DependencyMap;
+  /** Package specs whose local patches may change their dependency declarations. */
+  patchedDependencies?: Record<string, string>;
+  packages?: Record<string, BunPackageEntry>;
+};
+/** Root `package.json` fields that can be synced from the nested repository. */
+type SyncedField = "catalog" | "catalogs" | "overrides" | "patchedDependencies" | "trustedDependencies";
+/** All root fields in sync order; the default for `NestedWorkspaceConfig.fields`. */
+export declare const syncedFields: readonly SyncedField[];
+/** Field of the host `package.json` that holds `NestedWorkspaceConfig`. */
+declare const configField = "bun-nested-workspace";
+/**
+ * Names of host entries that came from the nested repository during the last sync.
+ *
+ * The sync maintains these lists to tell synced entries from the host's own ones,
+ * so it can remove entries that the nested repository dropped.
+ * Patches need no list: a synced patch is the one whose path lies inside the nested directory.
+ */
+interface SyncedEntries {
+  catalog?: string[];
+  catalogs?: Record<string, string[]>;
+  overrides?: string[];
+  trustedDependencies?: string[];
+}
+/** Configuration stored in the `bun-nested-workspace` field of the host `package.json`. */
+interface NestedWorkspaceConfig {
+  /** Directory of the nested repository checkout, relative to the host root. */
+  dir: string;
+  /** Root fields to sync; all of `syncedFields` when omitted. */
+  fields?: SyncedField[];
+  /** Maintained by the sync; do not edit by hand. */
+  synced?: SyncedEntries;
+}
+/** Validated `NestedWorkspaceConfig` with defaults applied. */
+interface ResolvedConfig {
+  /** Normalized relative POSIX path without a trailing slash. */
+  dir: string;
+  fields: readonly SyncedField[];
+  synced: SyncedEntries;
+}
+type Catalog = Record<string, string>;
+/** Root `package.json` fields this package reads or rewrites; other fields are preserved as is. */
+interface PackageManifest {
+  workspaces?: string[] | WorkspacesConfig;
+  catalog?: Catalog;
+  catalogs?: Record<string, Catalog>;
+  overrides?: Record<string, string>;
+  resolutions?: Record<string, string>;
+  patchedDependencies?: Record<string, string>;
+  trustedDependencies?: string[];
+  [configField]?: NestedWorkspaceConfig;
+  [key: string]: unknown;
+}
+/** Object form of the `workspaces` field of a root `package.json`. */
+interface WorkspacesConfig {
+  packages?: string[];
+  catalog?: Catalog;
+  catalogs?: Record<string, Catalog>;
+  [key: string]: unknown;
+}
+/** Host entry that a nested entry with the same name replaced during the sync. */
+interface OverriddenEntry {
+  /** Field path, such as `catalog`, `catalogs.testing`, or `overrides`. */
+  field: string;
+  name: string;
+  hostValue: string;
+  nestedValue: string;
+}
+/** Result of `syncManifest`. */
+interface ManifestSync {
+  manifest: PackageManifest;
+  overridden: OverriddenEntry[];
+  /**
+   * Whether the sync added `trustedDependencies` to a host that did not define it.
+   *
+   * The explicit list replaces the default trusted list of Bun,
+   * so host dependencies that relied on the default list no longer run their lifecycle scripts.
+   */
+  addedTrustedDependencies: boolean;
+}
+/**
+ * Returns the host root `package.json` with the configured root fields of the nested `package.json` merged in.
+ *
+ * A nested entry replaces a host entry with the same name, while the other host entries stay.
+ * Entries synced earlier and dropped by the nested repository are removed.
+ * Throws when the host and the nested repository patch the same package version,
+ * and when either side defines `resolutions` while `overrides` are synced.
+ */
+export declare function syncManifest(host: PackageManifest, nested: PackageManifest): ManifestSync;
+/** Difference between the expected and the actual value at a `package.json` path. */
+interface ManifestDifference {
+  /** Dot-separated path, such as `catalog.h3`. */
+  path: string;
+  expected?: unknown;
+  actual?: unknown;
+}
+/**
+ * Returns the differences of the synced root fields and the synced entry lists between two manifests.
+ *
+ * Key order and the order of `trustedDependencies` are ignored.
+ */
+export declare function diffManifests(expected: PackageManifest, actual: PackageManifest): ManifestDifference[];
+/** Parsed `bun.lock` with a supported `lockfileVersion`. */
+type Lockfile = BunLockFile & {
+  lockfileVersion: number;
+  workspaces: Record<string, BunLockWorkspace>;
+  packages: Record<string, BunPackageEntry>;
+};
+/**
+ * `bun.lock` format versions this package understands.
+ *
+ * The format is internal to Bun, so other versions are rejected instead of being rewritten blindly.
+ */
+export declare const supportedLockfileVersions: readonly number[];
+/** Parses `bun.lock` text and rejects lockfile versions outside `supportedLockfileVersions`. */
+export declare function parseLockfile(text: string, source?: string): Lockfile;
+/**
+ * Returns the nested lockfile with workspace and local paths relative to the host root.
+ *
+ * The nested root workspace is dropped, because it is not a workspace of the host.
+ */
+export declare function relocateLockfile(lock: Lockfile, dir: string): Lockfile;
+/**
+ * Returns the lockfile with root fields that affect resolution taken from the root `package.json`.
+ *
+ * `bun install` re-resolves dependencies whose catalog entry, override, or patch differs from the lockfile,
+ * so the merged lockfile must already record the synced root fields to keep the nested resolutions.
+ */
+export declare function applyManifestToLockfile(lock: Lockfile, manifest: PackageManifest): Lockfile;
+/**
+ * Merges the host lockfile with the relocated nested lockfile.
+ *
+ * Nested entries override host entries, so the nested packages keep the versions of the nested lockfile.
+ * A root entry overridden by the nested lockfile might not satisfy a dependency of a host package:
+ * such a dependency gets back its previous host resolution as a nested entry, so `bun install` keeps the host version
+ * instead of resolving the range again.
+ * A host workspace without a name cannot have nested entries, so `bun install` resolves its dependency again.
+ * When the previous host resolution does not satisfy the range either, which Bun lockfiles occasionally contain,
+ * the dependency gets the highest satisfying version recorded in either lockfile.
+ * Catalog dependencies are checked against the catalogs of the host lockfile, so apply the synced root fields
+ * to it first.
+ */
+export declare function mergeLockfiles(lock: Lockfile, nestedLock: Lockfile, dir: string): Lockfile;
+/** Dependency of a workspace package resolved differently than expected. */
+interface DependencyMismatch {
+  /** Workspace package name, or its path when the package has no name. */
+  workspace: string;
+  dependency: string;
+  /** Expected resolution, such as `name@1.2.3`; `undefined` when the dependency must not resolve. */
+  expected?: string;
+  /** Actual resolution; `undefined` when the dependency does not resolve. */
+  actual?: string;
+}
+/** Transitive dependency resolved differently than expected. */
+interface PackageMismatch {
+  /** Dependency chain from the nested workspace package, such as `["@nested/web", "nuxt", "@nuxt/kit"]`. */
+  path: string[];
+  /** Expected resolution, such as `name@1.2.3`. */
+  expected: string;
+  /** Actual resolution; `undefined` when the dependency does not resolve. */
+  actual?: string;
+}
+/** Returns the nested workspace paths that the host `workspaces` patterns do not include. */
+export declare function findUncoveredWorkspaces(manifest: PackageManifest, nestedLock: Lockfile): string[];
+/**
+ * Returns the paths of nested workspaces whose host lockfile entries differ from the relocated nested lockfile,
+ * including host entries of workspaces that the nested repository no longer has.
+ */
+export declare function findWorkspaceMismatches(lock: Lockfile, nestedLock: Lockfile, dir: string): string[];
+/**
+ * Returns the direct dependencies of nested workspaces that the host lockfile resolves differently than the nested one.
+ *
+ * Entries are compared like `findTransitiveMismatches` compares them, so a different integrity is a mismatch too.
+ */
+export declare function findDirectDependencyMismatches(lock: Lockfile, nestedLock: Lockfile): DependencyMismatch[];
+/**
+ * Returns the transitive dependencies of nested workspaces that the host lockfile resolves differently than the nested one.
+ *
+ * Walks the dependency edges from the nested workspaces through both lockfiles at once,
+ * so a different hoisting layout of the same versions is not a mismatch.
+ * Direct dependencies are covered by `findDirectDependencyMismatches`, and peer dependencies are not walked.
+ * Edges that the nested lockfile resolves outside their range are skipped, because the merge repairs them.
+ * Each mismatch is reported once, with the first dependency chain that reaches it, and its subtree is skipped.
+ */
+export declare function findTransitiveMismatches(lock: Lockfile, nestedLock: Lockfile): PackageMismatch[];
+/**
+ * Returns the external direct dependencies of host workspaces whose resolution differs between two host lockfiles.
+ *
+ * A dependency that changed to the root resolution of the nested lockfile is not reported, because the nested versions win,
+ * unless that resolution does not satisfy the host range.
+ */
+export declare function findOwnDependencyChanges(before: Lockfile, after: Lockfile, nestedLock: Lockfile, dir: string): DependencyMismatch[];
+/** Host and nested root files loaded from disk. */
+interface NestedWorkspace {
+  /** Absolute path of the host root. */
+  root: string;
+  config: ResolvedConfig;
+  manifest: PackageManifest;
+  /** Original text of the host `package.json`, used to preserve its formatting. */
+  manifestText: string;
+  nestedManifest: PackageManifest;
+  lock: Lockfile;
+  /** Nested lockfile relocated with `relocateLockfile`. */
+  nestedLock: Lockfile;
+}
+/** Loads the root `package.json` and `bun.lock` files of the host and of the nested checkout. */
+export declare function loadNestedWorkspace(root: string): Promise<NestedWorkspace>;
+/** Differences between the host files and the nested checkout; all lists are empty when the host is in sync. */
+interface CheckResult {
+  /** Synced root fields of the host `package.json` that differ from the nested ones. */
+  manifest: ManifestDifference[];
+  /** Nested workspaces whose host `bun.lock` entries differ from the nested `bun.lock`. */
+  workspaces: string[];
+  /** Direct dependencies of nested workspaces resolved differently than in the nested `bun.lock`. */
+  directDependencies: DependencyMismatch[];
+  /** Transitive dependencies of nested workspaces resolved differently than in the nested `bun.lock`. */
+  transitiveDependencies: PackageMismatch[];
+}
+/** Returns whether a check found no differences. */
+export declare function isInSync(result: CheckResult): boolean;
+/** Compares the host files with the nested checkout without writing anything or running `bun install`. */
+export declare function checkNestedWorkspace(workspace: NestedWorkspace): CheckResult;
+/** Error thrown when `bun install` exits with a non-zero code. */
+export declare class BunInstallError extends Error {
+  readonly exitCode: number;
+  constructor(exitCode: number);
+}
+/** Options of `syncNestedWorkspace`. */
+interface SyncOptions {
+  /** Arguments passed to `bun install`, such as `--lockfile-only`. */
+  installArgs?: readonly string[];
+  /**
+   * Called with the result of `syncManifest` once the host `package.json` is written, before `bun install` runs.
+   *
+   * It reports the changes of `package.json` even when `bun install` fails and the sync throws.
+   */
+  onManifestSync?: (sync: ManifestSync) => void;
+}
+/** Result of `syncNestedWorkspace`. */
+interface SyncResult {
+  /** Own dependencies of host workspaces that the sync re-resolved; the sync failed when this is not empty. */
+  ownDependencyChanges: DependencyMismatch[];
+  /** Check of the synced files; the sync failed when it is not in sync. */
+  check: CheckResult;
+}
+/**
+ * Syncs the host root `package.json` and `bun.lock` with the nested checkout.
+ *
+ * Writes the synced `package.json`, writes the merged `bun.lock`, runs `bun install`,
+ * and then compares the result with the nested checkout and with the original host resolutions.
+ */
+export declare function syncNestedWorkspace(root: string, options?: SyncOptions): Promise<SyncResult>;
+export type { CheckResult, DependencyMismatch, Lockfile, ManifestDifference, ManifestSync, NestedWorkspace, NestedWorkspaceConfig, OverriddenEntry, PackageManifest, PackageMismatch, ResolvedConfig, SyncOptions, SyncResult, SyncedEntries, SyncedField, WorkspacesConfig };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { t as BunInstallError, d as applyManifestToLockfile, n as checkNestedWorkspace, g as diffManifests, o as findDirectDependencyMismatches, s as findOwnDependencyChanges, c as findTransitiveMismatches, l as findUncoveredWorkspaces, u as findWorkspaceMismatches, r as isInSync, i as loadNestedWorkspace, f as mergeLockfiles, p as parseLockfile, m as relocateLockfile, h as supportedLockfileVersions, _ as syncManifest, a as syncNestedWorkspace, v as syncedFields } from "./workspace-BlJ1qGiO.mjs";