Merge pull request #2555 from ag-ui-protocol/mme/fix-release-relock-path-dependents

fix(release): re-lock packages that path-depend on a bumped Python package

Author: mme

scripts/release/prepare-release.test.ts

@@ -307,7 +307,12 @@ function haveUv(): boolean {
   return !probe.error && probe.status === 0;
 }
 
-async function buildFixture(): Promise<string> {
+async function buildFixture(
+  {
+    withDependent = false,
+    virtualReleased = false,
+  }: { withDependent?: boolean; virtualReleased?: boolean } = {},
+): Promise<string> {
   const root = mkdtempSync(join(tmpdir(), "prepare-release-fixture-"));
   mkdirSync(join(root, "scripts/release"), { recursive: true });
   mkdirSync(join(root, "fixture-pkg"), { recursive: true });
@@ -343,10 +348,12 @@ async function buildFixture(): Promise<string> {
       'requires-python = ">=3.10"',
       "dependencies = []",
       "",
-      "[build-system]",
-      'requires = ["hatchling"]',
-      'build-backend = "hatchling.build"',
-      "",
+      // `package = false` makes this a VIRTUAL project, which changes the source
+      // form a consumer's lock records for it from `directory` to `virtual`.
+      // A virtual project has no build backend -- it is not installable.
+      ...(virtualReleased
+        ? ["[tool.uv]", "package = false", ""]
+        : ["[build-system]", 'requires = ["hatchling"]', 'build-backend = "hatchling.build"', ""]),
     ].join("\n"),
   );
 
@@ -357,9 +364,59 @@ async function buildFixture(): Promise<string> {
     stdio: "ignore",
   });
   assert.equal(seed.status, 0, "fixture `uv lock` seed failed");
+
+  // A second, UNRELEASED package that consumes the released one through a
+  // `[tool.uv.sources]` path override — the shape integrations/langgraph/python
+  // has while PNI-274 is open. Its lock embeds the released package's VERSION,
+  // so bumping the released package alone strands it.
+  if (withDependent) {
+    mkdirSync(join(root, "fixture-dep"), { recursive: true });
+    writeFileSync(
+      join(root, "fixture-dep/pyproject.toml"),
+      [
+        "[project]",
+        'name = "fixture_dep"',
+        'version = "9.9.9"',
+        'requires-python = ">=3.10"',
+        'dependencies = ["fixture_pkg"]',
+        "",
+        "[tool.uv.sources]",
+        'fixture_pkg = { path = "../fixture-pkg" }',
+        "",
+        "[build-system]",
+        'requires = ["hatchling"]',
+        'build-backend = "hatchling.build"',
+        "",
+      ].join("\n"),
+    );
+    const depSeed = spawnSync("uv", ["lock"], {
+      cwd: join(root, "fixture-dep"),
+      stdio: "ignore",
+    });
+    assert.equal(depSeed.status, 0, "dependent fixture `uv lock` seed failed");
+  }
+
   return root;
 }
 
+// The version some OTHER lock records for a package it pulls in from a local
+// directory. uv writes the path source as `directory = "<rel>"`, and the
+// embedded version goes stale the moment the released package is bumped.
+function pathDepVersion(lockPath: string, relDir: string): string | null {
+  const blocks = readFileSync(lockPath, "utf8").split("[[package]]");
+  for (const block of blocks) {
+    // uv writes `directory`, `editable` or `virtual` depending on the target; the
+    // embedded version goes stale either way, so accept all three here.
+    const isPathSource = ["directory", "editable", "virtual"].some((form) =>
+      block.includes(`source = { ${form} = "${relDir}" }`),
+    );
+    if (!isPathSource) continue;
+    const match = block.match(/^version = "([^"]+)"/m);
+    if (match) return match[1];
+  }
+  return null;
+}
+
 function selfEntryVersion(lockPath: string): string | null {
   // The locked package is the one whose source is the local directory.
   const blocks = readFileSync(lockPath, "utf8").split("[[package]]");
@@ -445,3 +502,107 @@ test("a Python bump with no uv.lock reports only the manifest", {
 
   rmSync(root, { recursive: true, force: true });
 });
+
+// A released package can be consumed by another first-party package through a
+// `[tool.uv.sources]` path override. That consumer's uv.lock embeds the released
+// package's VERSION, so bumping the release alone leaves the consumer's lock
+// stale and the `uv lock --check` gate turns the release PR red in a package the
+// release did not even touch.
+//
+// This is the failure behind #2553: release/next bumped ag-ui-protocol
+// 0.1.20 -> 0.1.21 in sdks/python, and both the `lockfiles` and
+// `langgraph-python` jobs failed on integrations/langgraph/python/uv.lock —
+// which pins `ag-ui-protocol 0.1.20` from `directory = "../../../sdks/python"`.
+// Nothing was wrong with the PR; the bumper simply never relocked the consumer.
+test(
+  "a Python version bump re-locks packages that path-depend on the bumped one",
+  { timeout: 120_000, skip: haveUv() ? false : "uv not on PATH" },
+  async () => {
+    const root = await buildFixture({ withDependent: true });
+    const depLock = join(root, "fixture-dep/uv.lock");
+
+    assert.equal(
+      pathDepVersion(depLock, "../fixture-pkg"),
+      "0.1.0",
+      "dependent fixture seed lock",
+    );
+
+    const result = await runPrepareRelease(["--scope", "fixture-py", "--bump", "minor"], {
+      PREPARE_RELEASE_ROOT: root,
+    });
+    assert.equal(result.status, 0, `stderr: ${result.stderr}`);
+
+    // The regression: this stayed at 0.1.0, so `uv lock --check` failed here.
+    assert.equal(
+      pathDepVersion(depLock, "../fixture-pkg"),
+      "0.2.0",
+      "dependent uv.lock not re-locked",
+    );
+
+    // And it must be REPORTED, or the workflow never stages it — same failure
+    // mode as the released package's own lock.
+    const output = JSON.parse(result.stdout);
+    assert.deepEqual(
+      output.files,
+      // `files` is emitted sorted.
+      [
+        "fixture-dep/uv.lock",
+        "fixture-pkg/pyproject.toml",
+        "fixture-pkg/uv.lock",
+      ],
+      "dependent uv.lock missing from `files`",
+    );
+
+    rmSync(root, { recursive: true, force: true });
+  },
+);
+
+// uv records a path dependency in three different source forms, and the matcher
+// that finds dependents has to know all three or it silently skips one:
+//
+//     source = { directory = "../pkg" }   non-editable path source
+//     source = { editable  = "../pkg" }   editable path source
+//     source = { virtual   = "../pkg" }   target sets `[tool.uv] package = false`
+//
+// `virtual` is the easy one to miss, because it is the form that does NOT
+// correspond to something installable -- but uv still records `version = "..."`
+// for it, so it still goes stale on a bump and still fails `uv lock --check`.
+// Reported on #2555 review with a reproduction; this is that reproduction as a
+// test. Before the fix the matcher covered only directory|editable, so the
+// dependent below kept the old version and never reached `files`.
+test(
+  "a Python version bump re-locks a dependent that records the `virtual` path form",
+  { timeout: 120_000, skip: haveUv() ? false : "uv not on PATH" },
+  async () => {
+    const root = await buildFixture({ withDependent: true, virtualReleased: true });
+    const depLock = join(root, "fixture-dep/uv.lock");
+
+    // Guard the fixture itself: if uv ever stops emitting `virtual` here, this
+    // test would pass for the wrong reason, so assert the form is really present.
+    assert.match(
+      readFileSync(depLock, "utf8"),
+      /source = \{ virtual = "\.\.\/fixture-pkg" \}/,
+      "fixture did not produce a `virtual` path source -- test would be vacuous",
+    );
+    assert.equal(pathDepVersion(depLock, "../fixture-pkg"), "0.1.0", "dependent seed lock");
+
+    const result = await runPrepareRelease(["--scope", "fixture-py", "--bump", "minor"], {
+      PREPARE_RELEASE_ROOT: root,
+    });
+    assert.equal(result.status, 0, `stderr: ${result.stderr}`);
+
+    assert.equal(
+      pathDepVersion(depLock, "../fixture-pkg"),
+      "0.2.0",
+      "dependent uv.lock not re-locked through the `virtual` source form",
+    );
+
+    const output = JSON.parse(result.stdout);
+    assert.ok(
+      output.files.includes("fixture-dep/uv.lock"),
+      `dependent uv.lock missing from \`files\`: ${JSON.stringify(output.files)}`,
+    );
+
+    rmSync(root, { recursive: true, force: true });
+  },
+);

scripts/release/prepare-release.ts

@@ -383,11 +383,24 @@ function writePyVersion(pyprojectPath: string, newVersion: string): void {
  * crew-ai 0.3.0 (#2366) and aws-strands 0.2.5 (#2374) both needed a hand-pushed
  * "sync uv.lock" commit before their release PRs could go green.
  */
-function relockPythonPackage(pyprojectPath: string): string | null {
+function relockPythonPackage(repoRoot: string, pyprojectPath: string): string[] {
   const pkgDir = path.dirname(pyprojectPath);
   const lockPath = path.join(pkgDir, "uv.lock");
-  if (!fs.existsSync(lockPath)) return null;
 
+  const rewritten: string[] = [];
+  if (fs.existsSync(lockPath)) {
+    runUvLock(pkgDir);
+    rewritten.push(lockPath);
+  }
+  for (const dependentLock of findPathDependentLocks(repoRoot, pkgDir)) {
+    runUvLock(path.dirname(dependentLock));
+    rewritten.push(dependentLock);
+  }
+  return rewritten;
+}
+
+/** `uv lock` in one directory, with the missing-uv case spelled out. */
+function runUvLock(pkgDir: string): void {
   try {
     // stdout belongs to this script's JSON summary -- discard uv's so the
     // summary stays parseable, and pass its stderr through for diagnostics.
@@ -405,8 +418,68 @@ function relockPythonPackage(pyprojectPath: string): string | null {
     }
     throw error;
   }
+}
 
-  return lockPath;
+/**
+ * Every OTHER first-party uv.lock that pulls ``pkgDir`` in from the filesystem.
+ *
+ * A ``[tool.uv.sources]`` path override makes a consumer's lock carry the
+ * released package's VERSION, not just its name:
+ *
+ *     [[package]]
+ *     name = "ag-ui-protocol"
+ *     version = "0.1.20"
+ *     source = { directory = "../../../sdks/python" }
+ *
+ * So bumping the released package strands every such consumer, and the
+ * ``uv lock --check`` gate then fails in a package the release never touched.
+ * That is #2553: release/next bumped ag-ui-protocol 0.1.20 -> 0.1.21 and both
+ * the ``lockfiles`` and ``langgraph-python`` jobs went red on
+ * integrations/langgraph/python/uv.lock.
+ *
+ * Scope matches the gate this exists to satisfy (see the ``lockfiles`` job in
+ * unit-python-sdk.yml): first-party locks only, ``examples/`` excluded. Example
+ * locks are deliberately left alone -- they are not gated, several are stale
+ * today, and dojo-e2e relocks them non-frozen anyway, so touching them here
+ * would drag unrelated dependency churn into every release PR.
+ *
+ * Matching is on the resolved directory rather than the literal string, because
+ * the same package is reached by a different relative path from each consumer.
+ */
+function findPathDependentLocks(repoRoot: string, pkgDir: string): string[] {
+  const SKIP = new Set(["node_modules", ".venv", ".git", "examples"]);
+  const found: string[] = [];
+
+  const walk = (dir: string): void => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (SKIP.has(entry.name)) continue;
+        walk(path.join(dir, entry.name));
+      } else if (entry.name === "uv.lock" && dir !== pkgDir) {
+        found.push(path.join(dir, entry.name));
+      }
+    }
+  };
+  walk(repoRoot);
+
+  return found.filter((lockPath) => {
+    const lockDir = path.dirname(lockPath);
+    // uv has three directory-based source forms, and all three embed the
+    // dependency's version, so all three go stale on a bump:
+    //   directory -- a non-editable path source
+    //   editable  -- an editable path source
+    //   virtual   -- a path source whose target sets `[tool.uv] package = false`
+    // `virtual` is easy to miss because it is the one that does not correspond to
+    // something installable, but uv still records `version = "..."` for it and
+    // still fails `uv lock --check` when that version moves.
+    const sources = fs
+      .readFileSync(lockPath, "utf-8")
+      .matchAll(/^source = \{ (?:directory|editable|virtual) = "([^"]+)" \}$/gm);
+    for (const [, rel] of sources) {
+      if (path.resolve(lockDir, rel) === pkgDir) return true;
+    }
+    return false;
+  });
 }
 
 function readDotnetVersion(propsPath: string): string {
@@ -617,6 +690,7 @@ function readVersion(repoRoot: string, pkg: PackageConfig, versionSource?: strin
 
 /** Returns the absolute path of every file written (Maven fans out to modules). */
 function writeVersionFile(
+  repoRoot: string,
   filePath: string,
   ecosystem: PackageConfig["ecosystem"],
   newVersion: string
@@ -629,10 +703,10 @@ function writeVersionFile(
     return writeMavenVersion(filePath, newVersion);
   } else {
     writePyVersion(filePath, newVersion);
-    // The re-locked uv.lock is a second modified file and must be reported, or
-    // the release workflow never stages it -- see relockPythonPackage.
-    const lockPath = relockPythonPackage(filePath);
-    if (lockPath) return [filePath, lockPath];
+    // Each re-locked uv.lock -- this package's own, plus any consumer that
+    // path-depends on it -- is a further modified file and must be reported, or
+    // the release workflow never stages it. See relockPythonPackage.
+    return [filePath, ...relockPythonPackage(repoRoot, filePath)];
   }
   return [filePath];
 }
@@ -644,7 +718,7 @@ function writeVersion(
   versionSource?: string
 ): string[] {
   const filePath = getVersionFilePath(repoRoot, pkg, versionSource);
-  return writeVersionFile(filePath, pkg.ecosystem, newVersion);
+  return writeVersionFile(repoRoot, filePath, pkg.ecosystem, newVersion);
 }
 
 function computeNewVersion(
@@ -719,7 +793,7 @@ function main(): void {
     console.error(`[${args.scope}] Shared version: ${currentVersion} -> ${newVersion}`);
 
     if (versionSourceEcosystem === "dotnet" && args.bump !== "prerelease" && !args.dryRun) {
-      recordWritten(writeVersionFile(versionSourcePath, versionSourceEcosystem, newVersion));
+      recordWritten(writeVersionFile(repoRoot, versionSourcePath, versionSourceEcosystem, newVersion));
       const written = readVersionFile(versionSourcePath, versionSourceEcosystem);
       if (written !== newVersion) {
         console.error(`ERROR: Verification failed for ${scopeConfig.versionSource}: expected ${newVersion}, got ${written}`);
@@ -732,7 +806,7 @@ function main(): void {
     // -p:VersionSuffix and the props file stays put), the pom is the only place
     // a Maven version exists.
     if (versionSourceEcosystem === "maven" && !args.dryRun) {
-      recordWritten(writeVersionFile(versionSourcePath, versionSourceEcosystem, newVersion));
+      recordWritten(writeVersionFile(repoRoot, versionSourcePath, versionSourceEcosystem, newVersion));
       const written = readVersionFile(versionSourcePath, versionSourceEcosystem);
       if (written !== newVersion) {
         console.error(`ERROR: Verification failed for ${scopeConfig.versionSource}: expected ${newVersion}, got ${written}`);