Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 29 additions & 8 deletions resolver/local.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,25 @@ func NormalizeVersion(version string) string {
return strings.Split(v, "-")[0]
}

// CanonicalVersion strips a leading "v" and lowercases, but keeps prerelease
// and build metadata. Examples: "v27.0.0-alpha.0.0.0" → "27.0.0-alpha.0.0.0".
func CanonicalVersion(version string) string {
v := strings.TrimSpace(version)
return strings.TrimPrefix(strings.ToLower(v), "v")
}

// IsUnstableVersion reports whether version carries prerelease/build metadata
// (any '-' after the core x.y.z tag).
func IsUnstableVersion(version string) bool {
return strings.Contains(CanonicalVersion(version), "-")
}

// IsAlphaVersion reports whether version is a Node.js alpha prerelease
// (canonical form contains "-alpha").
func IsAlphaVersion(version string) bool {
return strings.Contains(CanonicalVersion(version), "-alpha")
}

// ScanInstalled returns all installed Node.js versions from the configured
// install root, sorted in descending semver order. Only directories that
// contain node.exe are included.
Expand Down Expand Up @@ -114,12 +133,14 @@ func LatestInstalledMatch(spec string, installed ...[]string) (string, bool) {
return "", false
}

// CheckInstalledLocally reports whether an exact x.y.z version is present on
// disk without making any network requests. Returns (canonicalVersion, true) on
// success. Non-exact specs (partial, aliases) always return ("", false).
// CheckInstalledLocally reports whether an exact x.y.z (or x.y.z-prerelease)
// version is present on disk without making any network requests. Returns
// (canonicalVersion, true) on success. Non-exact specs (partial, aliases)
// always return ("", false).
func CheckInstalledLocally(spec string) (string, bool) {
normalized := NormalizeVersion(spec)
parts := strings.Split(normalized, ".")
canonical := CanonicalVersion(spec)
core := NormalizeVersion(canonical)
parts := strings.Split(core, ".")
if len(parts) != 3 {
return "", false
}
Expand All @@ -133,11 +154,11 @@ func CheckInstalledLocally(spec string) (string, bool) {
}

root := settings.Expand(settings.Global().Root)
nodeExe := filepath.Join(root, "v"+normalized, "node.exe")
nodeExe := filepath.Join(root, "v"+canonical, "node.exe")
if _, err := os.Stat(nodeExe); err != nil {
return "", false
}
return normalized, true
return canonical, true
}

func isPartialVersionSpec(version string) bool {
Expand Down Expand Up @@ -175,7 +196,7 @@ func isExactVersionSpec(version string) bool {
}

// isNamedSpecifier reports CLI tokens that must be resolved through Find
// (latest, lts, default, current, user aliases) rather than local-only
// (latest, lts, alpha, default, current, user aliases) rather than local-only
// partial matching.
func isNamedSpecifier(version string) bool {
if isPartialVersionSpec(version) || isExactVersionSpec(version) {
Expand Down
132 changes: 113 additions & 19 deletions resolver/resolver.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,42 +12,68 @@ import (
semver "github.com/Masterminds/semver/v3"
)

// LatestIncludesPrerelease reports whether the reserved "latest" alias should
// resolve to the absolute tip of index.tab (including prereleases). Community
// builds leave this nil/false. Certified Governance builds may set it when
// HKLM LatestIncludesPrerelease=1.
var LatestIncludesPrerelease func() bool

// OnLegacyLatestResolved is invoked when "latest" resolves under
// LatestIncludesPrerelease. Certified builds use it for structured warnings.
var OnLegacyLatestResolved func(resolved string)

// FindVersion returns the best matching version for a given version string, along with its npm version.
// The input version string can be a full version (e.g. "v16.13.0"), a major.minor (e.g. "16.13"), or just a major version (e.g. "16").
// Aliases "latest", "lts", and "lts/<name>" are also accepted.
// Aliases "latest", "lts", "lts/<name>", and "alpha" are also accepted.
// The function will attempt to find the best match based on the available versions.
func Find(version string) (string, string, error) {
// Resolve aliases before normal version parsing.
lower := strings.ToLower(strings.TrimSpace(version))
v := strings.TrimPrefix(strings.TrimSpace(version), "v")
raw := strings.TrimPrefix(strings.TrimSpace(version), "v")
v := raw
isUserAlias := false
preservedPrerelease := ""

if _, err := strconv.Atoi(strings.Split(v, ".")[0]); err != nil {
if _, err := strconv.Atoi(strings.Split(strings.Split(v, "-")[0], ".")[0]); err != nil {
isUserAlias = true
}

if isUserAlias || lower == "latest" || lower == "lts" || strings.HasPrefix(lower, "lts/") {
if isUserAlias || lower == "latest" || lower == "lts" || lower == "alpha" || strings.HasPrefix(lower, "lts/") {
resolved, err := alias(lower)
if err != nil {
return "", "", err
}
v = resolved
if IsUnstableVersion(resolved) {
// Alias already produced a concrete prerelease tag (alpha / legacy latest).
return CanonicalVersion(resolved), "", nil
}
} else if IsUnstableVersion(raw) {
// Explicit prerelease/exact tag typed by the user — keep the full tag.
preservedPrerelease = CanonicalVersion(raw)
}

// Strip prerelease/build metadata for partial/exact matching. Explicit
// prerelease installs are not supported yet (reserved aliases alpha/beta);
// Strip prerelease/build metadata for partial numeric matching only.
// `latest` already skips prerelease rows so this strip does not invent a
// missing GA tag like 27.0.0 from 27.0.0-alpha.0.0.0 (nvm#1554).
v = strings.Split(v, "-")[0]
core := strings.Split(v, "-")[0]

if preservedPrerelease != "" {
// Exact prerelease: skip catalog so air-gapped installs work.
if isExactVersionSpec(core) {
return preservedPrerelease, "", nil
}
core = NormalizeVersion(preservedPrerelease)
}

// Exact x.y.z is already concrete (typed by the user, or after alias
// resolution). Skip index.tab so air-gapped `nvm install 24.22.1` can
// use a local archive without DNS.
if isExactVersionSpec(v) {
return NormalizeVersion(v), "", nil
if isExactVersionSpec(core) && preservedPrerelease == "" {
return NormalizeVersion(core), "", nil
}

parts := strings.Split(v, ".")
parts := strings.Split(core, ".")

major := parts[0]

Expand All @@ -70,20 +96,33 @@ func Find(version string) (string, string, error) {
return "", "", fmt.Errorf("version %s not found", version)
}

if preservedPrerelease != "" {
for _, row := range versions {
if strings.EqualFold(CanonicalVersion(row[0]), preservedPrerelease) {
return CanonicalVersion(row[0]), row[2], nil
}
}
return "", "", fmt.Errorf("version %s not found", version)
}

if minor != "" {
for _, v := range versions {
if strings.HasPrefix(v[0], major+"."+minor+".") {
for _, row := range versions {
tag := CanonicalVersion(row[0])
if strings.HasPrefix(tag, major+"."+minor+".") {
if patch == "" {
return v[0], v[2], nil
return tag, row[2], nil
}
if strings.EqualFold(v[0], major+"."+minor+"."+patch) {
return v[0], v[2], nil
if strings.EqualFold(NormalizeVersion(tag), major+"."+minor+"."+patch) && !IsUnstableVersion(tag) {
return tag, row[2], nil
}
if strings.EqualFold(tag, major+"."+minor+"."+patch) {
return tag, row[2], nil
}
}
}
}

return versions[0][0], versions[0][2], nil
return CanonicalVersion(versions[0][0]), versions[0][2], nil
}

// LTSName returns the LTS codename for the given version (e.g. "Jod", "Iron"),
Expand All @@ -104,7 +143,7 @@ func LTSName(version string) string {
}

// alias resolves a named alias to a concrete version string.
// Supported aliases: "latest", "lts", "lts/<name>", "default", "current".
// Supported aliases: "latest", "lts", "lts/<name>", "alpha", "default", "current".
func alias(version string) (string, error) {
v := strings.ToLower(strings.TrimSpace(version))

Expand All @@ -121,9 +160,27 @@ func alias(version string) (string, error) {
if err != nil {
return "", err
}
if LatestIncludesPrerelease != nil && LatestIncludesPrerelease() {
tag, err := latestTip(all)
if err != nil {
return "", err
}
if OnLegacyLatestResolved != nil {
OnLegacyLatestResolved(tag)
}
return tag, nil
}
return latestStable(all)
}

if v == "alpha" {
all, err := List()
if err != nil {
return "", err
}
return latestAlpha(all)
}

if v == "lts" {
all, err := List()
if err != nil {
Expand Down Expand Up @@ -177,7 +234,7 @@ func latestStable(versions [][]string) (string, error) {
if len(ver) == 0 {
continue
}
tag := strings.TrimPrefix(strings.TrimSpace(ver[0]), "v")
tag := CanonicalVersion(ver[0])
if tag == "" || strings.Contains(tag, "-") {
continue
}
Expand All @@ -186,6 +243,43 @@ func latestStable(versions [][]string) (string, error) {
return "", fmt.Errorf("no stable versions found")
}

// latestTip returns the absolute newest index.tab row, including prereleases.
// Used when Governance LatestIncludesPrerelease is enabled.
func latestTip(versions [][]string) (string, error) {
if len(versions) == 0 {
return "", fmt.Errorf("no versions found")
}
for _, ver := range versions {
if len(ver) == 0 {
continue
}
tag := CanonicalVersion(ver[0])
if tag == "" {
continue
}
return tag, nil
}
return "", fmt.Errorf("no versions found")
}

// latestAlpha returns the newest index.tab row whose version contains "-alpha".
func latestAlpha(versions [][]string) (string, error) {
if len(versions) == 0 {
return "", fmt.Errorf("no versions found")
}
for _, ver := range versions {
if len(ver) == 0 {
continue
}
tag := CanonicalVersion(ver[0])
if tag == "" || !IsAlphaVersion(tag) {
continue
}
return tag, nil
}
return "", fmt.Errorf("no alpha versions found")
}

// Resolve returns the best concrete Node.js version for the given input.
// It accepts:
// - Named aliases: "latest", "lts", "lts/<name>"
Expand All @@ -210,7 +304,7 @@ func Resolve(version string) (string, error) {
}

// Handle reserved aliases and plain/partial versions via Find, which covers
// "latest", "lts", "lts/<name>", "18", "18.20", "18.20.1", "v18.20.1".
// "latest", "lts", "lts/<name>", "alpha", "18", "18.20", "18.20.1", "v18.20.1".
resolved, _, err := Find(v)
if err == nil {
return resolved, nil
Expand Down
71 changes: 70 additions & 1 deletion resolver/resolver_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ package resolver
import "testing"

func TestFindExactVersionSkipsCatalog(t *testing.T) {
for _, spec := range []string{"24.22.1", "v24.22.1", "24.22.1-rc.1"} {
for _, spec := range []string{"24.22.1", "v24.22.1"} {
got, npm, err := Find(spec)
if err != nil {
t.Fatalf("Find(%q) error = %v", spec, err)
Expand All @@ -17,6 +17,19 @@ func TestFindExactVersionSkipsCatalog(t *testing.T) {
}
}

func TestFindExactPrereleaseKeepsTag(t *testing.T) {
got, npm, err := Find("24.22.1-rc.1")
if err != nil {
t.Fatalf("Find(prerelease) error = %v", err)
}
if got != "24.22.1-rc.1" {
t.Fatalf("Find(prerelease) = %q, want 24.22.1-rc.1", got)
}
if npm != "" {
t.Fatalf("Find(prerelease) npm = %q, want empty (no catalog)", npm)
}
}

func TestLatestStableSkipsPrereleaseHead(t *testing.T) {
// Mirrors nodejs.org/dist/index.tab order when an alpha leads the catalog.
rows := [][]string{
Expand All @@ -41,3 +54,59 @@ func TestLatestStableEmptyOrOnlyPrerelease(t *testing.T) {
t.Fatal("expected error when only prereleases exist")
}
}

func TestLatestAlphaPicksLeadingAlpha(t *testing.T) {
rows := [][]string{
{"27.0.0-alpha.0.0.0", "2026-10-29", "12.1.0", "", "-"},
{"26.13.0", "2026-10-28", "11.20.0", "Lithium", "-"},
{"26.0.0-alpha.1", "2026-01-01", "11.0.0", "", "-"},
}
got, err := latestAlpha(rows)
if err != nil {
t.Fatalf("latestAlpha error = %v", err)
}
if got != "27.0.0-alpha.0.0.0" {
t.Fatalf("latestAlpha = %q, want 27.0.0-alpha.0.0.0", got)
}
}

func TestLatestAlphaNone(t *testing.T) {
if _, err := latestAlpha([][]string{{"26.13.0", "", "", "", ""}}); err == nil {
t.Fatal("expected error when no alphas exist")
}
}

func TestLatestTipReturnsPrereleaseHead(t *testing.T) {
rows := [][]string{
{"27.0.0-alpha.0.0.0", "2026-10-29", "12.1.0", "", "-"},
{"26.13.0", "2026-10-28", "11.20.0", "Lithium", "-"},
}
got, err := latestTip(rows)
if err != nil {
t.Fatalf("latestTip error = %v", err)
}
if got != "27.0.0-alpha.0.0.0" {
t.Fatalf("latestTip = %q, want 27.0.0-alpha.0.0.0", got)
}
}

func TestIsAlphaAndUnstableHelpers(t *testing.T) {
if !IsAlphaVersion("v27.0.0-alpha.0.0.0") {
t.Fatal("expected alpha")
}
if IsAlphaVersion("27.0.0-rc.1") {
t.Fatal("rc must not count as alpha")
}
if !IsUnstableVersion("27.0.0-rc.1") {
t.Fatal("expected unstable")
}
if IsUnstableVersion("27.0.0") {
t.Fatal("GA must be stable")
}
}

func TestCanonicalVersion(t *testing.T) {
if got := CanonicalVersion("V27.0.0-Alpha.0.0.0"); got != "27.0.0-alpha.0.0.0" {
t.Fatalf("CanonicalVersion = %q", got)
}
}
4 changes: 2 additions & 2 deletions resolver/status.go
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ func resolveInstalledVersion(requestedVersion string, resolvePartialRemotely boo
}

// resolveLocalOnlyAlias maps default/current and user-defined aliases without
// touching the network. latest/lts still require the catalog via Find.
// touching the network. latest/lts/alpha still require the catalog via Find.
func resolveLocalOnlyAlias(version string) (string, bool) {
v := strings.ToLower(strings.TrimSpace(version))
if v == "" {
Expand All @@ -127,7 +127,7 @@ func resolveLocalOnlyAlias(version string) (string, bool) {
}
return active, true
}
if v == "latest" || v == "lts" || strings.HasPrefix(v, "lts/") {
if v == "latest" || v == "lts" || v == "alpha" || strings.HasPrefix(v, "lts/") {
return "", false
}

Expand Down
Loading