bun-nested-workspace 0.3.2 → 0.5.0

package/README.md

@@ -51,6 +51,8 @@ Then update the nested lockfile with `bun install --lockfile-only` in the direct
 bunx bun-nested-workspace
 ```
 
+A nested repository without workspace packages updates its lockfile in a separate clone.
+
 Do not run other `bun install`, `bun add`, or `bun remove` commands in the nested directory or in its package directories:
 
 - In the nested root, Bun runs them for the host: it writes the host lockfile and leaves the nested one stale.
@@ -72,6 +74,7 @@ The sync:
 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.
+A failed sync restores `package.json` and `bun.lock` to their contents before the run, while `node_modules` stays as the install left it.
 
 In a Docker build, run the sync with `--lockfile-only` in a stage that contains only the dependency files, before installing dependencies.
 The dependency install runs the `prepare` script of the nested root unless it gets `--ignore-scripts`.
@@ -96,7 +99,9 @@ Exclude `node_modules` and other large directories from the build context with `
 
 - `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.
+- `overrides` are merged by their keys, so a group such as `"micromatch": { "picomatch": "^2.3.2" }` replaces the host group with the same key as a whole.
+  The sync requires each `bun.lock` to be up to date with the overrides of its `package.json`.
+- `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.
@@ -104,7 +109,7 @@ Exclude `node_modules` and other large directories from the build context with `
 - `patchedDependencies` paths are rewritten through the nested directory, such as `nested/patches/exceljs@4.4.0.patch`.
   Bun warns on every install that it ignores `patchedDependencies` of the nested root package; keep them there, because the host applies the synced copies.
 
-A nested entry replaces a host entry with the same name, while the other host entries stay.
+A nested entry replaces a host entry with the same key, 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.
@@ -123,7 +128,7 @@ A dependency may only change to the version that the nested lockfile hoists to i
 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 other than the root 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.
+Only `bun.lock` with `lockfileVersion` 1, 2, or 3 is supported, because the lockfile format is internal to Bun.
 
 ## Check
 
@@ -132,7 +137,8 @@ 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 CI of the nested repository verifies that.
+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.
+Verify that in the CI of the nested repository with `bun install --lockfile-only` followed by `git diff --exit-code bun.lock`: `bun install --frozen-lockfile` misses some changes, such as a narrowed range that the locked version still satisfies.
 Use it in a non-blocking CI job that signals when a sync commit is due.
 
 It reports:
@@ -149,7 +155,7 @@ 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 verify that the host lockfile matches the host packages; `bun install --lockfile-only` followed by `git diff --exit-code bun.lock` 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
@@ -173,7 +179,8 @@ if (!isInSync(check)) {
 }
 ```
 
-`syncNestedWorkspace` writes the files and runs `bun install` before it checks the result, so a failed sync leaves the written files for inspection.
+`syncNestedWorkspace` writes the files and runs `bun install` before it checks the result.
+When `bun install` fails or the result shows differences, it restores both files before it throws or returns, and throws an error saying so when it cannot restore them.
 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.mjs

@@ -1,11 +1,12 @@
 #!/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-ChlHn5I8.mjs";
+import { a as isNestedWorkspace, i as isInSync, n as checkNestedWorkspace, o as loadNestedWorkspace, r as findNestedPackageDir, s as syncNestedWorkspace, t as BunInstallError, x as getErrorMessage } from "./workspace-CC5KeN8i.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.`;
+const restoredMessage = "Restored package.json and bun.lock to their contents before the sync.";
 /** 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")) {
@@ -23,7 +24,10 @@ async function runCli(args, root = process.cwd()) {
 		}
 		return await runSync(root, args);
 	} catch (error) {
-		if (error instanceof BunInstallError) return error.exitCode;
+		if (error instanceof BunInstallError) {
+			console.error(restoredMessage);
+			return error.exitCode;
+		}
 		console.error(getErrorMessage(error));
 		return 1;
 	}
@@ -51,7 +55,7 @@ async function runSync(root, installArgs) {
 	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.",
+			"Either the host bun.lock did not pin them: run bun install, commit bun.lock, and sync again.",
 			"Or the nested lockfile 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"));
@@ -59,10 +63,23 @@ async function runSync(root, installArgs) {
 	}
 	if (!isInSync(check)) {
 		console.error(["bun install did not keep the nested resolutions:", ...formatCheckResult(check)].join("\n"));
+		const workspace = await loadNestedWorkspace(root);
+		if (check.workspaces.some((workspacePath) => isNestedWorkspace(workspace, workspacePath))) console.error(await formatNestedLockfileUpdate(workspace));
 		exitCode = 1;
 	}
+	if (exitCode) console.error(restoredMessage);
 	return exitCode;
 }
+/** Formats how to update a nested lockfile that lags behind the nested package.json files. */
+async function formatNestedLockfileUpdate(workspace) {
+	const { dir } = workspace.config;
+	const packageDir = await findNestedPackageDir(workspace);
+	return packageDir ? `${dir}/bun.lock lags behind the package.json files of ${dir}. Update it and sync again:\n  (cd ${quoteShellArgument(packageDir)} && bun install --lockfile-only)` : `${dir}/bun.lock lags behind the package.json files of ${dir}. Update it with bun install --lockfile-only in a separate clone of the nested repository and sync again.`;
+}
+/** Quotes a value for a POSIX shell when it contains characters other than those of plain paths. */
+function quoteShellArgument(value) {
+	return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
 function printManifestSync({ overridden, addedTrustedDependencies }) {
 	if (overridden.length) console.log(["Nested entries replaced host entries:", ...overridden.map(formatOverridden)].join("\n"));
 	if (addedTrustedDependencies) console.warn([

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import semver from "semver";
 type DependencyMap = Record<string, string>;
 type BunLockWorkspace = {
   /**
@@ -5,6 +6,8 @@ type BunLockWorkspace = {
    * context for workspace-scoped lock keys.
    */
   name?: string;
+  /** Version of a workspace package; Bun leaves it out for the root workspace. */
+  version?: string;
   dependencies?: DependencyMap;
   devDependencies?: DependencyMap;
   optionalDependencies?: DependencyMap;
@@ -48,8 +51,12 @@ type BunLockFile = {
   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;
+  /**
+   * Canonical map Bun writes for package.json overrides and resolutions.
+   *
+   * A string value overrides a package by name; an object value groups the rules scoped to a package or its range.
+   */
+  overrides?: Record<string, string | DependencyMap>;
   /** Package specs whose local patches may change their dependency declarations. */
   patchedDependencies?: Record<string, string>;
   packages?: Record<string, BunPackageEntry>;
@@ -90,6 +97,8 @@ interface ResolvedConfig {
   synced: SyncedEntries;
 }
 type Catalog = Record<string, string>;
+/** Value of an `overrides` entry: a version spec, or a group of rules keyed by `"."` and dependency selectors. */
+type OverrideValue = string | Record<string, string>;
 /** Root `package.json` fields this package reads or rewrites; other fields are preserved as is. */
 interface PackageManifest {
   dependencies?: Record<string, string>;
@@ -99,7 +108,7 @@ interface PackageManifest {
   workspaces?: string[] | WorkspacesConfig;
   catalog?: Catalog;
   catalogs?: Record<string, Catalog>;
-  overrides?: Record<string, string>;
+  overrides?: Record<string, OverrideValue>;
   resolutions?: Record<string, string>;
   patchedDependencies?: Record<string, string>;
   trustedDependencies?: string[];
@@ -118,8 +127,8 @@ interface OverriddenEntry {
   /** Field path, such as `catalog`, `catalogs.testing`, or `overrides`. */
   field: string;
   name: string;
-  hostValue: string;
-  nestedValue: string;
+  hostValue: OverrideValue;
+  nestedValue: OverrideValue;
 }
 /** Result of `syncManifest`. */
 interface ManifestSync {
@@ -136,11 +145,13 @@ interface ManifestSync {
 /**
  * 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.
+ * A nested entry replaces a host entry with the same key, 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,
  * when either side defines `resolutions` while `overrides` are synced,
- * and when a synced `$name` override would refer to another range in the host root than in the nested root.
+ * when an override is one that `readManifestOverrides` rejects, when two overrides select the same packages,
+ * when a synced `$name` override would refer to another range in the host root than in the nested root,
+ * and when a synced override selects the nested root by a range that its version satisfies.
  */
 export declare function syncManifest(host: PackageManifest, nested: PackageManifest): ManifestSync;
 /** Difference between the expected and the actual value at a `package.json` path. */
@@ -184,7 +195,7 @@ export declare function relocateLockfile(lock: Lockfile, dir: string, rootName?:
  *
  * `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.
- * Records `$name` overrides with the range they refer to, as Bun does, and throws when `resolveOverrideValue` does.
+ * Records overrides in the form that Bun writes to `bun.lock`, with `$name` values replaced by the range they refer to.
  */
 export declare function applyManifestToLockfile(lock: Lockfile, manifest: PackageManifest): Lockfile;
 /**
@@ -199,8 +210,9 @@ export declare function applyManifestToLockfile(lock: Lockfile, manifest: Packag
  * 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
+ * Dependencies are checked against the catalogs and overrides of the host lockfile, so apply the synced root fields
  * to it first.
+ * The result has the higher `lockfileVersion` of the two, or version 1 when it has an entry that needs that version.
  */
 export declare function mergeLockfiles(lock: Lockfile, nestedLock: Lockfile, dir: string): Lockfile;
 /** Dependency of a workspace package resolved differently than expected. */
@@ -298,11 +310,15 @@ interface SyncOptions {
    */
   onManifestSync?: (sync: ManifestSync) => void;
 }
-/** Result of `syncNestedWorkspace`. */
+/**
+ * Result of `syncNestedWorkspace`.
+ *
+ * The sync failed and restored the host files when `ownDependencyChanges` is not empty or `isInSync(check)` is false.
+ */
 interface SyncResult {
-  /** Own dependencies of host workspaces that the sync re-resolved; the sync failed when this is not empty. */
+  /** Own dependencies of host workspaces that the sync re-resolved. */
   ownDependencyChanges: DependencyMismatch[];
-  /** Check of the synced files; the sync failed when it is not in sync. */
+  /** Check of the synced files. */
   check: CheckResult;
 }
 /**
@@ -310,6 +326,9 @@ interface SyncResult {
  *
  * 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.
+ * When `bun install` fails or the result differs, restores both files before it throws or returns,
+ * so that the next sync starts from the original host resolutions.
+ * Throws an error that says so when it cannot restore them.
  */
 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

@@ -1 +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-ChlHn5I8.mjs";
+export { t as BunInstallError, p as applyManifestToLockfile, n as checkNestedWorkspace, v as diffManifests, c as findDirectDependencyMismatches, l as findOwnDependencyChanges, u as findTransitiveMismatches, d as findUncoveredWorkspaces, f as findWorkspaceMismatches, i as isInSync, o as loadNestedWorkspace, m as mergeLockfiles, h as parseLockfile, g as relocateLockfile, _ as supportedLockfileVersions, y as syncManifest, s as syncNestedWorkspace, b as syncedFields } from "./workspace-CC5KeN8i.mjs";