fix(prerelease): unlink names the lockfile residue it cannot repin away (#336)

Reported against 0.24.0-rc.5 by an adopter verifying the #330/#323/#334 fixes. A regression
the #330 fix introduced, and the detector was already catching it correctly — what was
missing is that nothing told the user the fix is one install command.

WHAT BROKE. `link` correctly stopped deleting lockfiles (#330: a deletion is a destructive
edit to committed state unlink cannot undo, and it turns a targeted pin into a full
re-resolve, so an RC evaluation ends up testing "does the RC work" and "does a fresh
resolve work" in one diff). But `unlink` repins MANIFESTS only. A kept lockfile keeps its
`-rc` versions and private-registry tarball URLs, and `npm ci` resolves straight from the
lockfile — so a committed lockfile in that state sends every other machine and every CI run
to a registry it cannot reach. Closing one hole opened another; before #330 this state was
unreachable because the lockfile was gone.

The detector caught it. `unlink` then reported "left pre-release references behind — fix
them before pushing", which is true, unhelpful, and reads like a defect in the tool rather
than a remaining step.

`unlink` now names the offending lockfiles BEFORE running the detector, so the detector's
verdict reads as confirmation rather than a mystery, and prints the reconcile command per
ecosystem. The failure message says the lockfile is the residue and what to run.

IT STILL DOES NOT RUN INSTALLS, and that is deliberate rather than laziness: an install is
network-dependent and can fail, and running the wrong one silently migrates a project's
package manager — which is the exact hazard `npm_manager_for` already exists to avoid. So
the command is derived per install root from that root's own lockfile and PRINTED. Extended
to every ecosystem whose lockfile `link` used to drop, not just npm: uv, poetry, pipenv,
NuGet.

The residue check reads `PRERELEASE_RE` OUT OF THE DETECTOR rather than restating it. A
second copy of that regex would drift, and this function exists precisely to explain the
detector's own verdict — the two disagreeing would be worse than not explaining it at all.

ALSO FIXED, and it is the part that misleads at the worst moment: the detector's remediation
text still said unlink "drops the lockfile". It has not since #330, so the tool was telling
the user something untrue exactly when they were trying to work out why it failed. It now
states that unlink does NOT touch the lockfile and that repinning therefore cannot clear a
reference inside one.

Verified against a reproduction of the reported state (manifest repinned, lockfile still on
rc.5 with a private tarball URL): unlink names `package-lock.json`, prints `npm install`,
repins the manifest to 0.23.2, leaves the lockfile untouched, and exits non-zero with the
actionable message. CONTROLLED against an already-reconciled lockfile, which unlinks clean
with no residue reported — a false positive here would be worse than the bug, since it would
teach adopters to ignore the one check that prevents shipping a private-registry lockfile.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

tools/prerelease/detect-prerelease-pins.sh

@@ -355,8 +355,13 @@ Fix — from the project directory:
 
     tools/prerelease/prerelease-link.sh unlink --to <released-version>
 
-That removes the registry config, repins every vendor dependency, drops the lockfile,
-and re-runs this check.
+That removes the registry config, repins every vendor dependency, and re-runs this check.
+
+It does NOT delete or rewrite your lockfile — a lockfile is committed state `unlink` could
+not restore. So if the references above are in one (`package-lock.json`, `uv.lock`, …),
+repinning cannot clear them: reconcile with your project's own install command
+(`npm install` / `uv sync` / `dotnet restore --force-evaluate`) and run `check` again.
+`unlink` names the offending lockfiles and the exact command for them.
 MSG
   exit 1
 fi

tools/prerelease/prerelease-link.sh

@@ -291,6 +291,57 @@ npm_install_hint() {
   printf '%s' "$(IFS=' / '; echo "${cmds[*]}")"
 }
 
+# Lockfiles that STILL resolve from the pre-release after a repin — the residue `unlink`
+# leaves behind and cannot fix by editing manifests.
+#
+# WHY THIS EXISTS (#336). Before the #330 fix, `link` deleted the lockfile, so the
+# post-unlink install regenerated it from the public registry and this state was
+# unreachable. Keeping the lockfile closed one hole (a destructive edit to committed state,
+# and a full re-resolve that confounded "does the RC work" with "does a fresh resolve
+# work") and opened another: a repin rewrites the MANIFEST, while the lockfile keeps its
+# `-rc` versions and private-registry tarball URLs. `npm ci` then resolves straight from
+# the lockfile, sending every other machine and every CI run to a registry it cannot reach.
+#
+# Matched against the SAME `PRERELEASE_RE` the detector uses, sourced from it rather than
+# restated here — a second copy of that regex would drift, and this function exists to
+# explain the detector's own verdict.
+lockfiles_with_prerelease() {
+  local detector="$PROJECT/tools/prerelease/detect-prerelease-pins.sh"
+  [ -x "$detector" ] || detector="$HERE/detect-prerelease-pins.sh"
+  local re
+  re="$(grep -m1 "^PRERELEASE_RE=" "$detector" | cut -d"'" -f2)"
+  [ -n "$re" ] || return 0
+
+  local root prefix f
+  while IFS= read -r root; do
+    prefix="${root#"$PROJECT"/}"; [ "$prefix" = "$root" ] && prefix="" || prefix="$prefix/"
+    for f in package-lock.json npm-shrinkwrap.json yarn.lock pnpm-lock.yaml bun.lock; do
+      [ -e "$root/$f" ] || continue
+      grep -Eq -- "$re" "$root/$f" 2>/dev/null && printf '%s\n' "${prefix}${f}"
+    done
+  done < <(npm_install_roots)
+  # The same residue exists for every other ecosystem whose lockfile `link` used to drop.
+  for f in uv.lock poetry.lock Pipfile.lock packages.lock.json; do
+    [ -e "$PROJECT/$f" ] || continue
+    grep -Eq -- "$re" "$PROJECT/$f" 2>/dev/null && printf '%s\n' "$f"
+  done
+}
+
+# The reconcile command per ecosystem that still holds pre-release residue. `unlink` PRINTS
+# these rather than running them: an install is network-dependent, can fail, and — the
+# reason that matters — running the wrong one silently migrates a project's package manager,
+# which is exactly what npm_manager_for exists to avoid.
+reconcile_hints() {
+  local residue="$1"
+  case "$residue" in *package-lock.json*|*npm-shrinkwrap.json*|*yarn.lock*|*pnpm-lock.yaml*|*bun.lock*)
+    printf '  %s\n' "$(npm_install_hint)" ;;
+  esac
+  case "$residue" in *uv.lock*)           printf '  %s\n' "uv lock && uv sync" ;; esac
+  case "$residue" in *poetry.lock*)       printf '  %s\n' "poetry lock --no-update && poetry install" ;; esac
+  case "$residue" in *Pipfile.lock*)      printf '  %s\n' "pipenv lock && pipenv sync" ;; esac
+  case "$residue" in *packages.lock.json*) printf '  %s\n' "dotnet restore --force-evaluate" ;; esac
+}
+
 # Lockfiles are NOT dropped by default. Deleting one is a destructive edit to committed
 # state that `unlink` cannot undo, and it turns a targeted pin into a full re-resolution of
 # every unrelated transitive dependency — so a pre-release evaluation ends up testing "does
@@ -574,8 +625,24 @@ case "$ACTION" in
     has_mvn   && repin_mvn   "$TO"
     drop_lockfiles
     echo
+    # #336: a repin rewrites MANIFESTS; a kept lockfile still resolves the pre-release. Say
+    # so BEFORE the detector runs, so its verdict reads as confirmation rather than a
+    # mystery the user has to diagnose.
+    residue="$(lockfiles_with_prerelease)"
+    if [ -n "$residue" ]; then
+      warn "these lockfiles still resolve from the pre-release — repinning cannot fix a lockfile:"
+      printf '    %s\n' $residue
+      say "reconcile with:"
+      reconcile_hints "$residue"
+      echo
+    fi
     if run_detector; then
-      ok "unlinked and verified clean — reinstall to regenerate the lockfile from public registries"
+      ok "unlinked and verified clean"
+    elif [ -n "$residue" ]; then
+      # The detector is RIGHT and this is not a false positive — the residue is real and
+      # would send every `npm ci` to a private registry. It just has a one-command fix,
+      # which the old message left the user to work out.
+      die "unlink is incomplete: the lockfile(s) above still carry the pre-release. Run the reconcile command, then 'check'."
     else
       die "unlink left pre-release references behind (listed above) — fix them before pushing"
     fi