fix: preserve lockfile graph during versioning (#487)

Author: jan-kubica

.ai/local/agents.md

@@ -41,6 +41,10 @@ the browser, built on ProseMirror. Two published packages plus a dev playground:
   differential parity gate — extend them when you change parsing, layout, or
   editor interactions.
 - Return minimal data from public APIs; do not export types that have no consumer.
+- **Never delete or regenerate `bun.lock` to apply package version bumps.** Run
+  `bun scripts/check-lockfile-workspace-versions.ts --write`, then
+  `bun install --frozen-lockfile`. The synchronizer is the sole owner of cached
+  workspace self-versions; dependency-graph changes belong in an explicit install.
 
 ### Fidelity Consolidation
 

.changeset/README.md

@@ -28,7 +28,9 @@ without one of the above.
 1. PRs merge to `main`, each carrying its changeset(s).
 2. `release-pr.yml` maintains a **"Version Packages"** PR that applies the
    pending changesets: it bumps the affected `package.json` versions, updates the
-   changelogs, and re-syncs `bun.lock`.
+   changelogs, and surgically synchronizes workspace self-versions in `bun.lock`
+   before a frozen install. The resolved dependency graph is never regenerated
+   as a side effect of versioning.
 3. Merging that PR lands the version bumps on `main`. `publish.yml` builds and
    packs all six public packages without a publishing credential, then delegates
    registry state, dependency ordering, OIDC publishing, and per-package GitHub

.github/workflows/ci.yml

@@ -74,9 +74,8 @@ jobs:
       # `--frozen-lockfile` above only checks that the dependency graph still
       # satisfies bun.lock; it does not notice a workspace's cached "version"
       # field drifting behind its package.json (a plain `bun install` doesn't
-      # rewrite that field either — only a full lockfile regenerate does). See
-      # scripts/check-lockfile-workspace-versions.ts for the incident this
-      # guards against.
+      # rewrite that field either. The release path uses the same script in
+      # byte-preserving --write mode; CI keeps it in check-only mode.
       - name: Lockfile workspace-version check
         run: bun run check:lockfile-versions
 

AGENTS.md

@@ -307,6 +307,10 @@ the browser, built on ProseMirror. Two published packages plus a dev playground:
   differential parity gate — extend them when you change parsing, layout, or
   editor interactions.
 - Return minimal data from public APIs; do not export types that have no consumer.
+- **Never delete or regenerate `bun.lock` to apply package version bumps.** Run
+  `bun scripts/check-lockfile-workspace-versions.ts --write`, then
+  `bun install --frozen-lockfile`. The synchronizer is the sole owner of cached
+  workspace self-versions; dependency-graph changes belong in an explicit install.
 
 ### Fidelity Consolidation
 

package.json

@@ -56,7 +56,7 @@
     "validate-dist:vue": "bun scripts/validate-dist.ts vue",
     "api:update": "bun scripts/api-reports.ts --update",
     "api:check": "bun scripts/api-reports.ts",
-    "changeset:version": "changeset version && rm -f bun.lock && bun install",
+    "changeset:version": "changeset version && bun scripts/check-lockfile-workspace-versions.ts --write && bun install --frozen-lockfile",
     "bench": "bun benchmarks/index.ts",
     "bench:cross-language": "bun benchmarks/cross-language/run.ts",
     "parity": "bun parity/cli.ts",

scripts/bun-lock-workspace-versions.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import packageJson from "../package.json";
+import { syncWorkspaceVersions } from "./lib/bun-lock-workspace-versions";
+
+const fixture = `{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "packages/core": {
+      "name": "@stll/core",
+      "version": "1.0.0",
+      "dependencies": { "version": "do-not-touch" },
+    },
+    "packages/escaped\\u002dname": { "version": "2.0.0" },
+  },
+  "packages": [{ "version": "also-do-not-touch" }],
+}\n`;
+
+describe("bun.lock workspace self-version synchronization", () => {
+  test("changes only the exact workspace version string spans", () => {
+    const result = syncWorkspaceVersions(
+      fixture,
+      new Map([
+        ["packages/core", "1.1.0"],
+        ["packages/escaped-name", "2.1.0"],
+      ]),
+    );
+
+    expect(result.mismatches).toHaveLength(2);
+    expect(result.text).toBe(
+      fixture
+        .replace('"version": "1.0.0"', '"version": "1.1.0"')
+        .replace('"version": "2.0.0"', '"version": "2.1.0"'),
+    );
+    expect(result.text).toContain('"version": "do-not-touch"');
+    expect(result.text).toContain('"version": "also-do-not-touch"');
+  });
+
+  test("version-up/version-down is byte-identical", () => {
+    const up = syncWorkspaceVersions(fixture, new Map([["packages/core", "1.1.0"]])).text;
+    const down = syncWorkspaceVersions(up, new Map([["packages/core", "1.0.0"]])).text;
+
+    expect(down).toBe(fixture);
+  });
+
+  test("refuses to invent missing workspace structure", () => {
+    const result = syncWorkspaceVersions(fixture, new Map([["packages/missing", "1.0.0"]]));
+
+    expect(result.text).toBe(fixture);
+    expect(result.mismatches).toEqual([
+      { workspace: "packages/missing", expected: "1.0.0", actual: null },
+    ]);
+  });
+
+  test("release versioning cannot delete or regenerate bun.lock", () => {
+    const command = packageJson.scripts["changeset:version"];
+
+    expect(command).not.toMatch(/\brm\b/);
+    expect(command).toContain("check-lockfile-workspace-versions.ts --write");
+    expect(command).toEndWith("bun install --frozen-lockfile");
+  });
+});

scripts/check-lockfile-workspace-versions.ts

@@ -14,14 +14,13 @@
 // dependency range (see the @stll/docx-core ^0.4.0-vs-0.5.0 incident this
 // script was added to prevent).
 //
-// The only fix once it drifts is `rm bun.lock && bun install` (a full
-// regenerate). This script cross-checks each packages/*/package.json
-// `version` against the version bun.lock has cached for that workspace, so
-// the drift itself gets caught in CI instead of silently persisting.
+// This script is the single owner of workspace self-version synchronization:
+// check-only by default for CI, or byte-preserving repair with `--write`.
 
 import { panic } from "better-result";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
+import { syncWorkspaceVersions } from "./lib/bun-lock-workspace-versions";
 
 const ROOT = join(import.meta.dirname, "..");
 
@@ -37,31 +36,13 @@ const workspaceDirs = entries
 
 const lockText = await Bun.file(join(ROOT, "bun.lock")).text();
 
-// bun.lock is JSON-with-trailing-commas ("JSONC"-flavored), not strict JSON,
-// so a plain JSON.parse fails on it as-is. Trailing commas only ever appear
-// directly before a closing `}`/`]`, and that exact sequence cannot occur
-// inside any of bun.lock's own string values (workspace paths, package
-// names/versions/specifiers, or the base64 `sha512-...` integrity hashes),
-// so stripping them is a safe, structure-preserving normalize. Parsing the
-// whole file once and reading `workspaces[dir].version` from the resulting
-// object is immune to bun's key ordering or nested-object shape — unlike a
-// per-block regex, there is no block to mis-extract.
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-const parsedLock: unknown = JSON.parse(lockText.replace(/,(\s*[}\]])/g, "$1"));
-if (!isRecord(parsedLock) || !isRecord(parsedLock.workspaces)) {
-  panic("bun.lock did not parse into the expected { workspaces: {...} } shape");
+const args = process.argv.slice(2);
+if (args.some((arg) => arg !== "--write") || args.filter((arg) => arg === "--write").length > 1) {
+  panic("Usage: bun scripts/check-lockfile-workspace-versions.ts [--write]");
 }
-const { workspaces: lockWorkspaces } = parsedLock;
-
-const versionForWorkspace = (workspacePath: string): string | null => {
-  const entry = lockWorkspaces[workspacePath];
-  if (!isRecord(entry) || typeof entry.version !== "string") return null;
-  return entry.version;
-};
-
-const mismatches: string[] = [];
+const write = args[0] === "--write";
+const expectedVersions = new Map<string, string>();
+const packageNames = new Map<string, string>();
 
 for (const workspaceDir of workspaceDirs) {
   // A directory under packages/ is not necessarily a real workspace: skip
@@ -73,35 +54,47 @@ for (const workspaceDir of workspaceDirs) {
   const version = pkg.version;
   if (typeof name !== "string" || typeof version !== "string") continue;
 
-  const lockedVersion = versionForWorkspace(workspaceDir);
-  if (lockedVersion === null) {
-    mismatches.push(`${name} (${workspaceDir}): no bun.lock entry found`);
-    continue;
-  }
-  if (lockedVersion !== version) {
-    mismatches.push(
-      `${name} (${workspaceDir}): package.json is ${version}, bun.lock has ${lockedVersion}`,
-    );
-  }
+  expectedVersions.set(workspaceDir, version);
+  packageNames.set(workspaceDir, name);
 }
 
+const result = syncWorkspaceVersions(lockText, expectedVersions);
+const unrepairable = result.mismatches.filter(({ actual }) => actual === null);
+
+if (write && unrepairable.length === 0 && result.text !== lockText) {
+  await Bun.write(join(ROOT, "bun.lock"), result.text);
+  console.log(`bun.lock workspace-version sync: updated ${result.mismatches.length} workspace(s).`);
+  process.exit(0);
+}
+
+const mismatches = result.mismatches.map(({ workspace, expected, actual }) =>
+  actual === null
+    ? `${packageNames.get(workspace)} (${workspace}): no writable bun.lock version entry found`
+    : `${packageNames.get(workspace)} (${workspace}): package.json is ${expected}, bun.lock has ${actual}`,
+);
+
 if (mismatches.length > 0) {
   console.error(
     [
       "bun.lock workspace-version drift detected:",
       "",
       ...mismatches.map((line) => `  - ${line}`),
       "",
-      "A plain `bun install` will not fix this (it doesn't rewrite cached",
-      "workspace versions for entries that already exist). Regenerate the",
-      "lockfile instead:",
+      write
+        ? "The lockfile shape is incomplete; workspace entries must exist before they can be synchronized."
+        : "A plain `bun install` will not fix cached workspace self-versions. Synchronize them with:",
       "",
-      "    rm bun.lock && bun install",
+      "    bun scripts/check-lockfile-workspace-versions.ts --write",
+      "    bun install --frozen-lockfile",
       "",
       "Then commit the refreshed bun.lock.",
     ].join("\n"),
   );
   process.exit(1);
 }
 
-console.log("bun.lock workspace-version check: all workspace versions match. OK.");
+console.log(
+  write
+    ? "bun.lock workspace-version sync: already current. OK."
+    : "bun.lock workspace-version check: all workspace versions match. OK.",
+);